MCP 服务器

直接从 Claude Code、Cursor 和 Windsurf 等 AI 编程助手中使用 IPFS Ninja。上传文件、固定 CID、管理文件夹、查看使用情况 — 全部在 AI 对话中完成。

什么是 MCP？

Model Context Protocol (MCP) 是一个将 AI 助手连接到外部工具和数据源的开放标准。IPFS Ninja MCP 服务器提供 11 个工具，AI 模型可以在对话中调用这些工具来与您的 IPFS Ninja 帐户交互。

安装

npm 包

@ipfs-ninja/mcp-server

可在 npm 上获取。无需全局安装 — 通过 npx 运行。

前提条件

• 已安装 Node.js 18+
• 一个 IPFS Ninja API key（在 Dashboard > API Keys 获取）

Claude Code 设置

第 1 步：获取 API key

1. 在 ipfs.ninja 注册（免费）
2. 前往 Dashboard > API Keys
3. 点击 Create API key 并复制完整的 key（仅显示一次）

第 2 步：添加 MCP 服务器

在终端中运行以下命令：

claude mcp add ipfs-ninja \
  --transport stdio \
  -e IPFS_NINJA_API_KEY=bws_your_full_api_key_here \
  -- npx -y @ipfs-ninja/mcp-server

或者手动添加到 .claude/settings.json：

{
  "mcpServers": {
    "ipfs-ninja": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@ipfs-ninja/mcp-server"],
      "env": {
        "IPFS_NINJA_API_KEY": "bws_your_full_api_key_here"
      }
    }
  }
}

第 3 步：重启 Claude Code

退出并重新打开 Claude Code。输入 /mcp 确认 IPFS Ninja 服务器已连接。

第 4 步：开始使用

直接自然地与 Claude 对话即可：

你：把我的 README.md 上传到 IPFS
你：列出我最近的文件
你：我用了多少存储空间？
你：从 IPFS 网络固定 bafyabc123...
你：创建一个叫 "project-assets" 的文件夹

Cursor / Windsurf 设置

添加到您的 MCP 设置（Settings > MCP Servers）：

设置	值
Name	ipfs-ninja
Transport	stdio
Command	npx
Args	-y @ipfs-ninja/mcp-server
Environment	IPFS_NINJA_API_KEY=bws_...

可用工具

文件操作

工具	描述	示例提示
ipfs_upload	上传文件内容（base64 或文本）	"把这个 HTML 文件上传到 IPFS"
ipfs_upload_json	上传 JSON 对象	"把这个配置作为永久 JSON 存储到 IPFS"
ipfs_list	列出已上传的文件	"显示我最近的上传"
ipfs_get	通过 CID 获取文件元数据	"QmXyz... 是什么类型的文件？"
ipfs_delete	取消固定并删除文件	"从我的帐户中删除 QmXyz..."

固定

工具	描述	示例提示
ipfs_pin	从网络固定现有 CID	"把 bafyabc... 固定到我的帐户"
ipfs_pin_status	检查固定进度	"bafyabc... 固定完了吗？"

组织

工具	描述	示例提示
ipfs_folders_list	列出您的文件夹	"显示我的文件夹"
ipfs_folders_create	创建新文件夹	"创建一个叫 nft-metadata 的文件夹"

帐户

工具	描述	示例提示
ipfs_profile	获取套餐、存储、带宽信息	"我用了多少存储空间？"
ipfs_analytics	获取每日带宽和文件统计	"显示我这周的带宽使用情况"

示例工作流

部署静态网站

你：把我 dist/ 文件夹的内容上传到 IPFS
Claude：[上传每个文件，返回 CID]

你：index.html 的 CID 是什么？
Claude：[调用 ipfs_get]
     → QmXyz... — https://ipfs.ninja/ipfs/QmXyz...

NFT 元数据

你：创建一个叫 "my-collection" 的文件夹并上传这个 metadata JSON
Claude：[调用 ipfs_folders_create，然后 ipfs_upload_json]
     → 文件夹：my-collection
     → CID：QmAbc... — 永久元数据 URL，可用于您的智能合约

监控使用情况

你：我快到存储限制了吗？
Claude：[调用 ipfs_profile]
     → 套餐：Bodhi，存储：45.2 MB / 100 GB（0.04%）
     → 您还有充足的空间。

你：显示我这周的带宽
Claude：[调用 ipfs_analytics，days=7]
     → 2.3 MB 带宽，3 天内 45 个请求

从网络固定内容

你：固定 QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG 处的 IPFS readme
Claude：[调用 ipfs_pin]
     → 固定已启动！状态：固定中

你：完成了吗？
Claude：[调用 ipfs_pin_status]
     → 状态：已固定，大小：0.008 MB

故障排除

"IPFS_NINJA_API_KEY environment variable is required"

API key 未设置。确保 MCP 配置中的 env 部分包含正确的 key。

"API error 402: not enough storage"

您已达到套餐的存储限制。在 ipfs.ninja/pricing 升级或删除未使用的文件。

"API error 403: Forbidden"

您的 API key 可能无效或已过期。在 Dashboard > API Keys 创建新的。

服务器未显示在 /mcp 中

确保添加 MCP 服务器后已重启 Claude Code。检查是否已安装 Node.js 18+（node --version）。