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

# 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:

{
  "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:

{
  "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

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

# 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.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. 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