DEV Community

Cover image for Faça pin de arquivos no IPFS direto do Claude Code, Cursor e Windsurf (Servidor MCP)
Nacho Coll
Nacho Coll

Posted on

Faça pin de arquivos no IPFS direto do Claude Code, Cursor e Windsurf (Servidor MCP)

#ai #mcp #showdev #web3

E aí, devs — sou o Nacho, parte do time da BWS (Blockchain Web Services). Acabamos de lançar o IPFS.NINJA, um serviço gerenciado de pinning para IPFS, e uma das integrações que eu pessoalmente mais uso é o servidor MCP que permite fazer upload de arquivos, pin de CIDs e consultar uso de armazenamento direto do Claude Code, Cursor ou Windsurf — só conversando com a IA em portuguê.

Disclosure completo: eu trabalho neste produto. Este post é um walkthrough transparente do time que construíu a ferramenta.

O que o MCP entrega

Model Context Protocol (MCP) é um padrão aberto para conectar assistentes de IA a ferramentas externas. Nosso servidor MCP expõe 12 tools que o modelo pode chamar no meio da conversa contra sua conta IPFS.NINJA:

Operações de arquivo

  • ipfs_upload — Upload de conteúdo (base64 ou texto)
  • ipfs_upload_json — Upload de objeto JSON
  • ipfs_import_car — Importar CAR file (DAG import)
  • ipfs_list — Listar arquivos enviados
  • ipfs_get — Metadados de arquivo por CID
  • ipfs_delete — Despinar e deletar um arquivo

Pinning

  • ipfs_pin — Pinar um CID existente da rede
  • ipfs_pin_status — Verificar progresso do pin

Organização

  • ipfs_folders_list / ipfs_folders_create

Conta

  • ipfs_profile — Plano, armazenamento, banda
  • ipfs_analytics — Estatísticas diárias

Resultado prático: você para de alternar entre terminal, dashboard e editor.

Setup no Claude Code (60 segundos)

1. Crie sua conta em ipfs.ninja (grátis) e gere uma API key em Dashboard → API Keys. Copie a chave (é mostrada uma vez só).

2. Adicione o servidor MCP:

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

Ou adicione manualmente no .claude/settings.json:

{
  "mcpServers": {
    "ipfs-ninja": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@ipfs-ninja/mcp-server"],
      "env": {
        "IPFS_NINJA_API_KEY": "bws_sua_api_key_completa_aqui"
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

3. Reinicie o Claude Code. Digite /mcp para confirmar que ipfs-ninja está conectado.

O pacote npm é @ipfs-ninja/mcp-server — sem necessidade de instalação global, roda via npx. Requer Node.js 18+.

Setup no Cursor / Windsurf

Em Settings → MCP Servers, adicione:

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

Como é na prática

Depois de instalado, você só conversa:

Você: Faz upload do meu README.md para o IPFS
Você: Lista meus arquivos recentes
Você: Quanto storage estou usando?
Você: Pina o CID bafyabc123... da rede IPFS
Você: Cria uma pasta chamada "project-assets"
Enter fullscreen mode Exit fullscreen mode

O modelo escolhe a tool certa, chama nossa API, e retorna um CID + uma URL pública de gateway tipo https://ipfs.ninja/ipfs/<CID>. Sem ficar copiando comando curl, sem trocar de janela.

Workflows reais que isso destrava

Deploy de site estático no IPFS direto do Claude Code:

Você: Faz upload do conteúdo da minha pasta dist/ para o IPFS
Claude: [faz upload de cada arquivo, retorna CIDs]
Você: Qual o CID do index.html?
Claude: [chama ipfs_get] → QmXyz... — https://ipfs.ninja/ipfs/QmXyz...
Enter fullscreen mode Exit fullscreen mode

Pipeline de metadados de NFT:

Você: Cria uma pasta "my-collection" e faz upload deste JSON de metadata
Claude: [chama ipfs_folders_create, depois ipfs_upload_json]
        → Pasta: my-collection
        → CID: QmAbc... — URL permanente pronta para o smart contract
Enter fullscreen mode Exit fullscreen mode

Monitorar uso sem sair do editor:

Você: Tô perto do meu limite de storage?
Claude: [chama ipfs_profile]
        → Plano: Bodhi, Storage: 45.2 MB / 100 GB (0.04%)
Você: Mostra minha banda essa semana
Claude: [chama ipfs_analytics com days=7]
        → 2.3 MB de banda, 45 requests em 3 dias
Enter fullscreen mode Exit fullscreen mode

Pinar conteúdo existente da rede:

Você: Pina o readme do IPFS em QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG
Claude: [chama ipfs_pin] → Pin iniciado! Status: pinning
Você: Já acabou?
Claude: [chama ipfs_pin_status] → Status: pinned, Tamanho: 0.008 MB
Enter fullscreen mode Exit fullscreen mode

Troubleshooting (os três problemas que de fato acontecem)

  • IPFS_NINJA_API_KEY environment variable is required — o bloco env do MCP config está sem a chave.
  • API error 402: not enough storage — você atingiu o limite do plano. Faz upgrade ou apaga arquivos não usados.
  • Servidor não aparece no /mcp — esqueceu de reiniciar o editor depois de adicionar. Confirma também que node --version ≥ 18.

Experimenta

Se você construir algo legal com isso (auto-pinning de assets de blog no commit, fluxo de mint de NFT direto da IA, etc.), conta nos comentários. A gente lê tudo.

— Nacho, time BWS

Top comments (0)