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）。