DEV Community

Cover image for Pin Files to IPFS Straight from Claude Code, Cursor, and Windsurf (MCP Server)
Nacho Coll
Nacho Coll

Posted on

Pin Files to IPFS Straight from Claude Code, Cursor, and Windsurf (MCP Server)

#ai #mcp #showdev #web3

Hi devs — Nacho here from the BWS (Blockchain Web Services) team. We just shipped IPFS.NINJA, a managed IPFS pinning service, and one of the integrations I personally use the most is the MCP server that lets you upload files, pin CIDs, and check storage usage directly from Claude Code, Cursor, or Windsurf — just by asking the AI in plain English.

Full disclosure: I work on this product. This post is a transparent walkthrough from the team that built it.

What MCP gives you

Model Context Protocol (MCP) is an open standard for connecting AI coding assistants to external tools. Our MCP server exposes 12 tools the model can call mid-conversation against your IPFS.NINJA account:

File operations

  • ipfs_upload — Upload file content (base64 or text)
  • ipfs_upload_json — Upload a JSON object
  • ipfs_import_car — Import a CAR file (DAG import)
  • ipfs_list — List your uploaded files
  • ipfs_get — Get file metadata by CID
  • ipfs_delete — Unpin and delete a file

Pinning

  • ipfs_pin — Pin an existing CID from the network
  • ipfs_pin_status — Check pin progress

Organization

  • ipfs_folders_list / ipfs_folders_create

Account

  • ipfs_profile — Plan, storage, bandwidth
  • ipfs_analytics — Daily bandwidth and file stats

The net effect: you stop context-switching between your terminal, the dashboard, and your editor.

Setup for Claude Code (60 seconds)

1. Sign up at ipfs.ninja (free) and create an API key from Dashboard → API Keys. Copy it (it's only shown once).

2. Add the MCP server:

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

Or add manually to .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"
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

3. Restart Claude Code. Type /mcp to confirm ipfs-ninja is connected.

The npm package is @ipfs-ninja/mcp-server — no global install needed, runs via npx. Requires Node.js 18+.

Setup for Cursor / Windsurf

In Settings → MCP Servers, add:

Setting Value
Name ipfs-ninja
Transport stdio
Command npx
Args -y @ipfs-ninja/mcp-server
Environment IPFS_NINJA_API_KEY=bws_...

What it actually feels like

Once installed, you just talk to the assistant:

You: Upload my README.md to IPFS
You: List my recent files
You: How much storage am I using?
You: Pin bafyabc123... from the IPFS network
You: Create a folder called "project-assets"
Enter fullscreen mode Exit fullscreen mode

The model picks the right tool, calls our API, and returns a CID + a public gateway URL like https://ipfs.ninja/ipfs/<CID>. No copy-pasting curl commands, no context switching.

Real workflows it unlocks

Deploy a static site to IPFS from Claude Code:

You: Upload the contents of my dist/ folder to IPFS
Claude: [uploads each file, returns CIDs]
You: What's the CID for index.html?
Claude: [calls ipfs_get] → QmXyz... — https://ipfs.ninja/ipfs/QmXyz...
Enter fullscreen mode Exit fullscreen mode

NFT metadata pipeline:

You: Create a folder called "my-collection" and upload this metadata JSON
Claude: [calls ipfs_folders_create, then ipfs_upload_json]
        → Folder: my-collection
        → CID: QmAbc... — permanent metadata URL ready for your smart contract
Enter fullscreen mode Exit fullscreen mode

Monitor usage without leaving the editor:

You: Am I close to my storage limit?
Claude: [calls ipfs_profile]
        → Plan: Bodhi, Storage: 45.2 MB / 100 GB (0.04%)
You: Show my bandwidth this week
Claude: [calls ipfs_analytics with days=7]
        → 2.3 MB bandwidth, 45 requests across 3 days
Enter fullscreen mode Exit fullscreen mode

Pin existing content from the network:

You: Pin the IPFS readme at QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG
Claude: [calls ipfs_pin] → Pin initiated! Status: pinning
You: Is it done?
Claude: [calls ipfs_pin_status] → Status: pinned, Size: 0.008 MB
Enter fullscreen mode Exit fullscreen mode

Troubleshooting (the three things that actually go wrong)

  • IPFS_NINJA_API_KEY environment variable is required — the env block in your MCP config is missing the key.
  • API error 402: not enough storage — you've hit your plan's storage limit. Upgrade or delete unused files.
  • Server not showing in /mcp — you forgot to restart the editor after adding the server. Also check node --version is ≥ 18.

Try it

If you build something cool with it (auto-pinning blog assets on commit, AI-driven NFT minting flows, etc.), I'd love to hear about it in the comments.

— Nacho, BWS team

Top comments (0)