MCP-IPFS

<p align="center"> <img src="https://raw.githubusercontent.com/ipfs/logo/master/ipfs-logo.svg" alt="IPFS Logo" width="120" /> </p>

<h1 align="center">MCP-IPFS</h1>

<p align="center"> <strong>A Model Context Protocol server for IPFS operations</strong> </p>

<p align="center"> Give Claude full control over the InterPlanetary File System </p>

<p align="center"> <a href="#-quick-start">Quick Start</a> • <a href="#-features">Features</a> • <a href="#-tools">Tools</a> • <a href="#%EF%B8%8F-configuration">Configuration</a> • <a href="#-architecture">Architecture</a> • <a href="#-contributing">Contributing</a> </p>

<p align="center"> <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT" /> <img src="https://img.shields.io/badge/MCP-compatible-brightgreen.svg" alt="MCP Compatible" /> <img src="https://img.shields.io/badge/IPFS-Helia-blue.svg" alt="IPFS: Helia" /> <img src="https://img.shields.io/badge/TypeScript-5.0+-3178c6.svg" alt="TypeScript 5.0+" /> <img src="https://img.shields.io/badge/tools-34-orange.svg" alt="Tools: 34" /> </p>

---

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

<table> <tr> <td width="50%">

📦 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

</td> <td width="50%">

🔭 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

</td> </tr> <tr> <td>

⚡ 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

</td> <td>

🔌 Pluggable Backends

• Helia (embedded) - zero external dependencies
• Kubo (planned) - connect to existing go-ipfs nodes
• Pinning Services (planned) - Pinata, Web3.Storage

</td> </tr> </table>

---

🛠 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

---

<p align="center"> Built with ❤️ for the decentralized web </p>