MCP-IPFS
A Model Context Protocol server for IPFS operations
Give Claude full control over the InterPlanetary File System
Quick Start •
Features •
Tools •
Configuration •
Architecture •
Contributing
What is MCP-IPFS?
MCP-IPFS is a Model Context Protocol (MCP) server that enables Claude and other AI assistants to interact directly with IPFS (InterPlanetary File System). It provides a comprehensive suite of tools for content-addressed storage, peer-to-peer networking, and decentralized data management.
Built on Helia (the modern JavaScript IPFS implementation), with a pluggable architecture ready for Kubo and remote pinning services.
Why MCP-IPFS?
| Without MCP-IPFS | With MCP-IPFS |
|---|---|
| Manual IPFS CLI commands | Claude handles IPFS operations directly |
| Copy-paste CIDs between tools | Seamless content-addressed workflows |
| No visibility into node status | Full observability of peers, bandwidth, DHT |
| Long operations block interaction | Background jobs with progress tracking |
| Single IPFS backend | Pluggable: Helia, Kubo, pinning services |
🚀 Quick Start
Prerequisites
- Node.js 18+
- Claude Code CLI or any MCP-compatible client
Installation```bash
Clone the repository
git clone https://github.com/EricGrill/mcp-ipfs.git
cd mcp-ipfs
Install dependencies
npm install
Build
npm run build
### Add to Claude Code
Add to your `~/.claude/claude_desktop_config.json`:```json
{
"mcpServers": {
"ipfs": {
"command": "node",
"args": ["/path/to/mcp-ipfs/dist/index.js"]
}
}
}
Verify Installation```
You: What's the IPFS node status?
Claude: [Uses node_status tool]
Node is running with peer ID QmXxx...
Connected to 12 peers
Repository size: 45.2 MB
---
## ✨ Features
### 📦 Content Operations
- **Add & retrieve** text, JSON, files, directories
- **Pin management** to prevent garbage collection
- **IPNS publishing** for mutable names
- **MFS** (Mutable File System) for familiar file operations
- **DAG operations** for advanced IPLD data structures
### 🔭 Node Monitoring
- **Node identity** and health status
- **Peer connections** with latency and direction
- **Bandwidth statistics** total and per-protocol
- **Repository stats** and garbage collection
- **DHT operations** for peer/content discovery
### ⚡ Background Jobs
- **Async operations** for large files and slow networks
- **Progress tracking** with real-time updates
- **Job management** - list, poll, cancel
- **Auto-detection** - small ops return immediately
### 🔌 Pluggable Backends
- **Helia** (embedded) - zero external dependencies
- **Kubo** (planned) - connect to existing go-ipfs nodes
- **Pinning Services** (planned) - Pinata, Web3.Storage
---
## 🛠 Tools
### Content Tools
| Tool | Description |
|------|-------------|
| `ipfs_add` | Add text, JSON, or file to IPFS. Returns CID. |
| `ipfs_get` | Retrieve content by CID |
| `ipfs_pin` | Pin content to prevent garbage collection |
| `ipfs_unpin` | Unpin content |
| `ipfs_pins_list` | List all pinned CIDs |
| `ipfs_add_directory` | Add entire directory, returns root CID |
| `ipfs_ls` | List contents of directory CID |
| `ipfs_get_file` | Get specific file from directory by path |
### IPNS Tools
| Tool | Description |
|------|-------------|
| `ipns_publish` | Publish CID to IPNS name |
| `ipns_resolve` | Resolve IPNS name to current CID |
| `ipns_keys_list` | List available IPNS keys |
### MFS Tools (Mutable File System)
| Tool | Description |
|------|-------------|
| `mfs_write` | Write content to mutable path |
| `mfs_read` | Read content from MFS path |
| `mfs_ls` | List directory contents |
| `mfs_mkdir` | Create directory |
| `mfs_rm` | Remove file or directory |
| `mfs_mv` | Move/rename file or directory |
| `mfs_flush` | Flush MFS to get root CID |
### DAG Tools
| Tool | Description |
|------|-------------|
| `dag_put` | Store IPLD data, returns CID |
| `dag_get` | Retrieve IPLD node, optionally traverse path |
### Node Tools
| Tool | Description |
|------|-------------|
| `node_id` | Get peer ID, public key, versions |
| `node_status` | Quick health check |
| `node_version` | Detailed version info |
| `peers_list` | Connected peers with details |
| `peers_count` | Simple peer count |
| `bandwidth_stats` | Network bandwidth metrics |
| `swarm_connect` | Connect to peer by multiaddr |
| `swarm_disconnect` | Disconnect from peer |
| `repo_stats` | Repository statistics |
| `repo_gc` | Trigger garbage collection |
### DHT Tools
| Tool | Description |
|------|-------------|
| `dht_find_peer` | Find addresses for peer ID via DHT |
| `dht_find_providers` | Find peers providing a CID (configurable limit) |
| `dht_provide` | Announce content availability to the network |
### Job Tools
| Tool | Description |
|------|-------------|
| `job_status` | Get status of background job |
| `jobs_list` | List all jobs |
| `job_cancel` | Cancel running job |
---
## ⚙️ Configuration
### Configuration File
Create `mcp-ipfs.config.json` in the project root:```json
{
"backend": "helia",
"persistence": {
"enabled": true,
"path": "./ipfs-data"
},
"helia": {
"libp2p": {
"addresses": ["/ip4/0.0.0.0/tcp/4002"],
"bootstrap": true
}
},
"jobs": {
"maxConcurrent": 3,
"defaultTimeout": 300000
}
}
Environment Variables
Environment variables override config file settings:
| Variable | Description | Default |
|---|---|---|
MCP_IPFS_BACKEND |
Backend to use | helia |
MCP_IPFS_PERSISTENCE_ENABLED |
Enable persistent storage | true |
MCP_IPFS_DATA_PATH |
Data directory path | ./ipfs-data |
MCP_IPFS_BOOTSTRAP |
Connect to bootstrap nodes | true |
MCP_IPFS_JOBS_MAX_CONCURRENT |
Max concurrent jobs | 3 |
MCP_IPFS_JOBS_TIMEOUT |
Default job timeout (ms) | 300000 |
Persistence Modes
Persistent (default):
- Content survives server restarts
- Uses LevelDB blockstore
- Recommended for production
In-memory:
- Content lost on restart
- Faster for testing
- Set persistence.enabled: false
🏗 Architecture```
┌─────────────────────────────────────────────────┐
│ Claude │
└─────────────────────┬───────────────────────────┘
│ MCP Protocol (JSON-RPC)
┌─────────────────────▼───────────────────────────┐
│ MCP-IPFS Server │
│ │
│ ┌───────────┐ ┌───────────┐ ┌─────────────┐ │
│ │ Content │ │ Node │ │ Job │ │
│ │ Tools │ │ Tools │ │ Manager │ │
│ └─────┬─────┘ └─────┬─────┘ └──────┬──────┘ │
│ │ │ │ │
│ └──────────────┼───────────────┘ │
│ │ │
│ ┌───────────▼───────────┐ │
│ │ Backend Layer │ │
│ │ (IPFSBackend) │ │
│ └───────────┬───────────┘ │
└───────────────────────┼─────────────────────────┘
│
┌─────────────┼─────────────┐
┌─────▼────┐ ┌─────▼────┐ ┌─────▼────┐
│ Helia │ │ Kubo │ │ Pinning │
│(embedded)│ │ API │ │ Services │
└──────────┘ └──────────┘ └──────────┘
✓ planned planned
### Key Components
| Component | Responsibility |
|-----------|----------------|
| **Content Tools** | IPFS add/get/pin, IPNS, MFS, DAG operations |
| **Node Tools** | Status, peers, bandwidth, repo, DHT, config |
| **Job Manager** | Queue long operations, track progress, enable polling |
| **Backend Layer** | Abstract IPFS implementation details |
### Backend Interface```typescript
interface IPFSBackend {
// Lifecycle
start(): Promise<void>;
stop(): Promise<void>;
// Content
add(content: Uint8Array, options?: AddOptions): Promise<CID>;
get(cid: CID): Promise<Uint8Array>;
pin(cid: CID): Promise<void>;
unpin(cid: CID): Promise<void>;
// Node info
id(): Promise<PeerInfo>;
peers(): Promise<PeerConnection[]>;
// ... etc
}
📁 Project Structure```
mcp-ipfs/
├── src/
│ ├── index.ts # Entry point
│ ├── server.ts # MCP server setup
│ ├── tools/
│ │ ├── content.ts # Content operations
│ │ ├── node.ts # Node monitoring
│ │ └── jobs.ts # Job management
│ ├── backends/
│ │ ├── interface.ts # Backend abstraction
│ │ └── helia.ts # Helia implementation
│ ├── jobs/
│ │ └── manager.ts # Job queue
│ └── config.ts # Configuration
├── test/
│ ├── content.test.ts
│ ├── node.test.ts
│ └── jobs.test.ts
├── docs/
│ └── plans/ # Design documents
├── package.json
├── tsconfig.json
└── mcp-ipfs.config.json
---
## 🧪 Development```bash
# Install dependencies
npm install
# Run in development mode
npm run dev
# Run tests
npm test
# Build for production
npm run build
# Lint
npm run lint
🤝 Contributing
Contributions are welcome! Please read our contributing guidelines before submitting PRs.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
📚 Related Resources
Learn More
- IPFS Documentation
- Helia Documentation
- Model Context Protocol
- MCP TypeScript SDK
Community
- IPFS Forums
- IPFS Discord
📜 License
MIT License - see LICENSE for details.
🙏 Acknowledgments
- Protocol Labs for IPFS and Helia
- Anthropic for Claude and MCP
- The agents-skills-plugins marketplace for inspiration
Built with ❤️ for the decentralized web
