<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](https://github.com/ipfs/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

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

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

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](https://docs.ipfs.tech/)
- [Helia Documentation](https://helia.io/)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)

### Community
- [IPFS Forums](https://discuss.ipfs.tech/)
- [IPFS Discord](https://discord.gg/ipfs)

---

## 📜 License

MIT License - see [LICENSE](LICENSE) for details.

---

## 🙏 Acknowledgments

- [Protocol Labs](https://protocol.ai/) for IPFS and Helia
- [Anthropic](https://anthropic.com/) for Claude and MCP
- The [agents-skills-plugins](https://github.com/EricGrill/agents-skills-plugins) marketplace for inspiration

---

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