MCP Server

Sử dụng IPFS Ninja trực tiếp từ các trợ lý lập trình AI như Claude Code, Cursor và Windsurf. Tải tệp lên, ghim CID, quản lý thư mục và kiểm tra mức sử dụng — tất cả từ cuộc trò chuyện AI của bạn.

MCP là gì?

Model Context Protocol (MCP) là một tiêu chuẩn mở để kết nối trợ lý AI với các công cụ và nguồn dữ liệu bên ngoài. MCP server của IPFS Ninja cung cấp 11 công cụ mà mô hình AI có thể gọi trong cuộc trò chuyện để tương tác với tài khoản IPFS Ninja của bạn.

Cài đặt

Gói npm

@ipfs-ninja/mcp-server

Có sẵn trên npm. Không cần cài đặt toàn cục — chạy qua npx.

Điều kiện tiên quyết

• Đã cài Node.js 18+
• API key IPFS Ninja (lấy tại Dashboard > API Keys)

Thiết lập cho Claude Code

Bước 1: Lấy API key của bạn

1. Đăng ký tại ipfs.ninja (miễn phí)
2. Truy cập Dashboard > API Keys
3. Nhấn Create API key và sao chép toàn bộ key (chỉ hiển thị một lần)

Bước 2: Thêm MCP server

Chạy lệnh này trong terminal:

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

Hoặc thêm thủ công vào .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"
      }
    }
  }
}

Bước 3: Khởi động lại Claude Code

Thoát và mở lại Claude Code. Gõ /mcp để xác nhận server IPFS Ninja đã kết nối.

Bước 4: Bắt đầu sử dụng

Chỉ cần trò chuyện tự nhiên với Claude:

Bạn: Tải README.md của tôi lên IPFS
Bạn: Liệt kê các tệp gần đây
Bạn: Tôi đang dùng bao nhiêu dung lượng?
Bạn: Ghim bafyabc123... từ mạng IPFS
Bạn: Tạo thư mục tên "project-assets"

Thiết lập cho Cursor / Windsurf

Thêm vào cài đặt MCP (Settings > MCP Servers):

Cài đặt	Giá trị
Name	ipfs-ninja
Transport	stdio
Command	npx
Args	-y @ipfs-ninja/mcp-server
Environment	IPFS_NINJA_API_KEY=bws_...

Công cụ có sẵn

Thao tác tệp

Công cụ	Mô tả	Ví dụ lệnh
ipfs_upload	Tải nội dung tệp lên (base64 hoặc văn bản)	"Tải tệp HTML này lên IPFS"
ipfs_upload_json	Tải lên một đối tượng JSON	"Lưu cấu hình này thành JSON vĩnh viễn trên IPFS"
ipfs_list	Liệt kê các tệp đã tải lên	"Hiển thị các tệp tải lên gần đây"
ipfs_get	Lấy metadata tệp theo CID	"QmXyz... là loại tệp gì?"
ipfs_delete	Gỡ ghim và xóa tệp	"Xóa QmXyz... khỏi tài khoản của tôi"

Ghim

Công cụ	Mô tả	Ví dụ lệnh
ipfs_pin	Ghim CID hiện có từ mạng	"Ghim bafyabc... vào tài khoản của tôi"
ipfs_pin_status	Kiểm tra tiến trình ghim	"bafyabc... đã ghim xong chưa?"

Tổ chức

Công cụ	Mô tả	Ví dụ lệnh
ipfs_folders_list	Liệt kê thư mục	"Hiển thị thư mục của tôi"
ipfs_folders_create	Tạo thư mục mới	"Tạo thư mục tên nft-metadata"

Tài khoản

Công cụ	Mô tả	Ví dụ lệnh
ipfs_profile	Lấy thông tin gói, dung lượng, băng thông	"Tôi đang dùng bao nhiêu dung lượng?"
ipfs_analytics	Lấy thống kê băng thông và tệp hàng ngày	"Hiển thị mức sử dụng băng thông tuần này"

Ví dụ quy trình làm việc

Triển khai trang web tĩnh

Bạn: Tải nội dung thư mục dist/ lên IPFS
Claude: [tải từng tệp, trả về CID]

Bạn: CID của index.html là gì?
Claude: [gọi ipfs_get]
     → QmXyz... — https://ipfs.ninja/ipfs/QmXyz...

NFT metadata

Bạn: Tạo thư mục "my-collection" và tải metadata JSON này lên
Claude: [gọi ipfs_folders_create, sau đó ipfs_upload_json]
     → Thư mục: my-collection
     → CID: QmAbc... — URL metadata vĩnh viễn sẵn sàng cho smart contract

Theo dõi mức sử dụng

Bạn: Tôi có gần đạt giới hạn dung lượng không?
Claude: [gọi ipfs_profile]
     → Gói: Bodhi, Dung lượng: 45.2 MB / 100 GB (0.04%)
     → Bạn còn rất nhiều dung lượng.

Bạn: Hiển thị băng thông tuần này
Claude: [gọi ipfs_analytics với days=7]
     → 2.3 MB băng thông, 45 yêu cầu trong 3 ngày

Ghim nội dung từ mạng

Bạn: Ghim IPFS readme tại QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG
Claude: [gọi ipfs_pin]
     → Đã bắt đầu ghim! Trạng thái: đang ghim

Bạn: Xong chưa?
Claude: [gọi ipfs_pin_status]
     → Trạng thái: đã ghim, Kích thước: 0.008 MB

Khắc phục sự cố

"IPFS_NINJA_API_KEY environment variable is required"

API key chưa được thiết lập. Đảm bảo phần env trong cấu hình MCP có key chính xác.

"API error 402: not enough storage"

Bạn đã đạt giới hạn dung lượng của gói. Nâng cấp tại ipfs.ninja/pricing hoặc xóa các tệp không dùng.

"API error 403: Forbidden"

API key có thể không hợp lệ hoặc đã hết hạn. Tạo key mới tại Dashboard > API Keys.

Server không hiển thị trong /mcp

Đảm bảo bạn đã khởi động lại Claude Code sau khi thêm MCP server. Kiểm tra Node.js 18+ đã được cài đặt (node --version).