Provides tools for interacting with IPFS, enabling content-addressed storage, peer-to-peer networking, pinning, IPNS, MFS, DAG operations, and node monitoring.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MCP-IPFS What's the IPFS node status?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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 |
Related MCP server: Filesystem MCP Server
Node.js 18+
Claude Code CLI or any MCP-compatible client
# Clone the repository
git clone https://github.com/EricGrill/mcp-ipfs.git
cd mcp-ipfs
# Install dependencies
npm install
# Build
npm run buildAdd to your ~/.claude/claude_desktop_config.json:
{
"mcpServers": {
"ipfs": {
"command": "node",
"args": ["/path/to/mcp-ipfs/dist/index.js"]
}
}
}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 MBAdd & 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 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
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
Helia (embedded) - zero external dependencies
Kubo (planned) - connect to existing go-ipfs nodes
Pinning Services (planned) - Pinata, Web3.Storage
Tool | Description |
| Add text, JSON, or file to IPFS. Returns CID. |
| Retrieve content by CID |
| Pin content to prevent garbage collection |
| Unpin content |
| List all pinned CIDs |
| Add entire directory, returns root CID |
| List contents of directory CID |
| Get specific file from directory by path |
Tool | Description |
| Publish CID to IPNS name |
| Resolve IPNS name to current CID |
| List available IPNS keys |
Tool | Description |
| Write content to mutable path |
| Read content from MFS path |
| List directory contents |
| Create directory |
| Remove file or directory |
| Move/rename file or directory |
| Flush MFS to get root CID |
Tool | Description |
| Store IPLD data, returns CID |
| Retrieve IPLD node, optionally traverse path |
Tool | Description |
| Get peer ID, public key, versions |
| Quick health check |
| Detailed version info |
| Connected peers with details |
| Simple peer count |
| Network bandwidth metrics |
| Connect to peer by multiaddr |
| Disconnect from peer |
| Repository statistics |
| Trigger garbage collection |
Tool | Description |
| Find addresses for peer ID via DHT |
| Find peers providing a CID (configurable limit) |
| Announce content availability to the network |
Tool | Description |
| Get status of background job |
| List all jobs |
| Cancel running job |
Create mcp-ipfs.config.json in the project root:
{
"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 override config file settings:
Variable | Description | Default |
| Backend to use |
|
| Enable persistent storage |
|
| Data directory path |
|
| Connect to bootstrap nodes |
|
| Max concurrent jobs |
|
| Default job timeout (ms) |
|
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
┌─────────────────────────────────────────────────┐
│ Claude │
└─────────────────────┬───────────────────────────┘
│ MCP Protocol (JSON-RPC)
┌─────────────────────▼───────────────────────────┐
│ MCP-IPFS Server │
│ │
│ ┌───────────┐ ┌───────────┐ ┌─────────────┐ │
│ │ Content │ │ Node │ │ Job │ │
│ │ Tools │ │ Tools │ │ Manager │ │
│ └─────┬─────┘ └─────┬─────┘ └──────┬──────┘ │
│ │ │ │ │
│ └──────────────┼───────────────┘ │
│ │ │
│ ┌───────────▼───────────┐ │
│ │ Backend Layer │ │
│ │ (IPFSBackend) │ │
│ └───────────┬───────────┘ │
└───────────────────────┼─────────────────────────┘
│
┌─────────────┼─────────────┐
┌─────▼────┐ ┌─────▼────┐ ┌─────▼────┐
│ Helia │ │ Kubo │ │ Pinning │
│(embedded)│ │ API │ │ Services │
└──────────┘ └──────────┘ └──────────┘
✓ planned plannedComponent | 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 |
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
}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# Install dependencies
npm install
# Run in development mode
npm run dev
# Run tests
npm test
# Build for production
npm run build
# Lint
npm run lintContributions 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
MIT License - see LICENSE for details.
Protocol Labs for IPFS and Helia
Anthropic for Claude and MCP
The agents-skills-plugins marketplace for inspiration
This server cannot be deployed
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Augments MCP Server - A comprehensive framework documentation provider for Claude Code
Hosted MCP server connecting claude.ai, ChatGPT and other AI apps to your own computer
Talk to your public-facing AI from any MCP client — Claude, ChatGPT, Cursor, Cline, Windsurf.
