MCP IPFS Server (storacha.network) 🛰️

1# 🪐 MCP IPFS Server (storacha.network) 🛰️
2 
3![Screenshot](https://raw.githubusercontent.com/alexbakers/mcp-ipfs/refs/heads/main/mcp-ipfs.png?neon-game)
4 
5[![Publish Docker](https://github.com/alexbakers/mcp-ipfs/actions/workflows/publish-docker.yml/badge.svg)](https://github.com/alexbakers/mcp-ipfs/actions/workflows/publish-docker.yml) [![Publish NPM](https://github.com/alexbakers/mcp-ipfs/actions/workflows/publish-npm.yml/badge.svg)](https://github.com/alexbakers/mcp-ipfs/actions/workflows/publish-npm.yml) [![npm version](https://badge.fury.io/js/mcp-ipfs.svg)](https://badge.fury.io/js/mcp-ipfs)
6[![smithery badge](https://smithery.ai/badge/@alexbakers/mcp-ipfs)](https://smithery.ai/server/@alexbakers/mcp-ipfs)
7 
8A Node.js server implementing the [Model Context Protocol (MCP)](https://github.com/ModelContextProtocol/specification) for interacting with the [storacha.network](https://storacha.network/) platform via the `w3` command-line interface (`@web3-storage/w3cli`).
9 
10This server empowers language models 🤖 and other MCP clients to manage storacha.network spaces, upload/download data, manage delegations, and perform various other tasks by seamlessly wrapping `w3` commands.
11 
12## ✨ Features
13 
14- Wraps the `w3` CLI for native integration with storacha.network.
15- Provides MCP tools covering a wide range of `w3` functionality:
16  - 🔑 **Authentication & Agent:** `w3_login`, `w3_reset`, `w3_account_ls` (for checking authorization)
17  - 📦 **Space Management:** `w3_space_ls`, `w3_space_use`, `w3_space_info`, `w3_space_add`, `w3_space_provision` (Note: `w3_space_create` must be run manually due to interactive prompts)
18  - 💾 **Data Management:** `w3_up`, `w3_ls`, `w3_rm`
19  - 🔗 **Sharing:** `w3_open` (generates w3s.link URL)
20  - 🤝 **Delegations & Proofs:** `w3_delegation_create`, `w3_delegation_ls`, `w3_delegation_revoke`, `w3_proof_add`, `w3_proof_ls`
21  - 🔐 **Keys & Tokens:** `w3_key_create`, `w3_bridge_generate_tokens`
22  - ⚙️ **Advanced Storage (`w3 can ...`):** Blob, CAR, Upload, Index, Access Claim, Filecoin Info management
23  - 💳 **Account & Billing:** `w3_plan_get`, `w3_coupon_create`, `w3_usage_report`
24 
25## 🛠️ Prerequisites
26 
27- **Node.js:** Version 22.0.0 or higher (`node -v`).
28- **`w3` CLI:** The server executes `w3` commands directly. Ensure `@web3-storage/w3cli` is installed globally and configured:
29  ```bash
30  npm install -g @web3-storage/w3cli
31  w3 login <your-email@example.com>
32  # Follow email verification steps
33  ```
34- **Environment Variable:** The `w3_login` tool requires the `W3_LOGIN_EMAIL` environment variable to be set to the same email used for `w3 login`.
35 
36## 🏗️ Project Structure
37 
38The codebase is organized as follows:
39 
40```
41src/
42├── index.ts          # Main server entry point, MCP setup, request routing
43├── schemas.ts        # Zod schemas defining input arguments for each tool
44├── tool_handlers.ts  # Implementation logic for each MCP tool
45├── utils.ts          # Helper functions (e.g., running w3 commands, parsing JSON)
46└── utils/
47    └── logger.ts     # Basic logger configuration
48```
49 
50## 🚀 Usage with MCP Clients
51 
52This server can be used with any MCP-compatible client. You need to configure your client to connect to this server.
53 
54### Example: NPX (Recommended for simple local use)
55 
56This assumes `npm` and the prerequisites are met.
57 
58```json
59{
60  "mcpServers": {
61    "ipfs": {
62      "command": "npx",
63      "args": ["-y", "mcp-ipfs"],
64      "env": {
65        "W3_LOGIN_EMAIL": "your-email@example.com"
66      }
67    }
68  }
69}
70```
71 
72### Example: Docker
73 
74Build the image first (see Build section) or use the pre-built image `alexbakers/mcp-ipfs`.
75 
76```json
77{
78  "mcpServers": {
79    "mcp-ipfs": {
80      "command": "docker",
81      "args": [
82        "run",
83        "-i",
84        "--rm",
85        "-v",
86        "/path/to/your/project:/path/to/your/project",
87        "-e",
88        "W3_LOGIN_EMAIL",
89        "alexbakers/mcp-ipfs"
90      ],
91      "env": {
92        "W3_LOGIN_EMAIL": "your-email@example.com"
93      }
94    }
95  }
96}
97```
98 
99#### 📝 Note on Paths:
100 
101Several `w3` commands require **absolute filesystem paths** (e.g., `w3_up`, `w3_delegation_create --output`, `w3_proof_add`, `w3_can_blob_add`, `w3_can_store_add`).
102 
103- **NPX:** Provide absolute paths from your host machine.
104- **Docker:** Provide absolute paths _inside the container_. If interacting with files from your host (e.g., uploading), you **must** mount the relevant host directory into the container using the `-v` flag (e.g., `-v /Users/me/project:/Users/me/project`) and then use the _container path_ (e.g., `/Users/me/project/my_file.txt`) in the tool arguments.
105 
106## 📦 Build
107 
108Clone the repository and install dependencies:
109 
110```bash
111git clone https://github.com/alexbakers/mcp-ipfs.git
112cd mcp-ipfs
113npm install
114```
115 
116Build the TypeScript code:
117 
118```bash
119npm run build
120```
121 
122You can then run the server directly:
123 
124```bash
125# Ensure W3_LOGIN_EMAIL is set in your environment
126export W3_LOGIN_EMAIL="your-email@example.com"
127node dist/index.js
128```
129 
130Or publish it (if you have the rights):
131 
132```bash
133npm publish
134```
135 
136### 🐳 Docker Build
137 
138Build the Docker image:
139 
140```bash
141# Build locally (replace with your username/repo and desired tag)
142docker build -t alexbakers/mcp-ipfs .
143```
144 
145## 📜 License
146 
147This MCP server is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
148