Pin Files to IPFS Diretamente do Código Claude, Cursor e Windsurf (Servidor MCP)

Oi devs — Nacho aqui da equipe BWS (Blockchain Web Services). Acabamos de lançar IPFS.NINJA, um serviço gerenciado de pinagem IPFS, e uma das integrações que eu pessoalmente uso mais é o servidor MCP que permite que você faça upload de arquivos, pinagem de CIDs e verifique o uso de armazenamento diretamente do Claude Code, Cursor ou Windsurf — apenas perguntando à IA em inglês simples.

Divulgação completa: eu trabalho neste produto. Este post é um walkthrough transparente da equipe que o construiu.

O que o MCP oferece

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

Operações de arquivo

• ipfs_upload — Fazer upload do conteúdo do arquivo (base64 ou texto)
• ipfs_upload_json — Fazer upload de um objeto JSON
• ipfs_import_car — Importar um arquivo CAR (importação DAG)
• ipfs_list — Listar seus arquivos enviados
• ipfs_get — Obter metadados do arquivo por CID
• ipfs_delete — Desvincular e excluir um arquivo

Pinagem

• ipfs_pin — Pinagem de um CID existente da rede
• ipfs_pin_status — Verificar o progresso da pinagem

Organização

• ipfs_folders_list / ipfs_folders_create

Conta

• ipfs_profile — Plano, armazenamento, largura de banda
• ipfs_analytics — Estatísticas diárias de largura de banda e arquivos

O efeito líquido: você para de alternar entre seu terminal, o painel e seu editor.

Configuração para Claude Code (60 segundos)

1. Inscreva-se em ipfs.ninja (grátis) e crie uma chave de API no Painel → Chaves de API. Copie-a (ela é exibida apenas uma vez).

2. Adicione o servidor 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

Ou adicione manualmente ao .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. Reinicie o Claude Code. Digite /mcp para confirmar que ipfs-ninja está conectado.

O pacote npm é @ipfs-ninja/mcp-server — nenhuma instalação global necessária, roda via npx. Requer Node.js 18+.

Configuração para Cursor / Windsurf

Nas Configurações → Servidores MCP, adicione:

Como realmente se sente

Uma vez instalado, você apenas conversa com o assistente:

Você: Faça upload do meu README.md para IPFS
Você: Liste meus arquivos recentes
Você: Quanto armazenamento estou usando?
Você: Pin bafyabc123... da rede IPFS
Você: Crie uma pasta chamada "project-assets"

O modelo escolhe a ferramenta certa, chama nossa API e retorna um CID + uma URL de gateway público como https://ipfs.ninja/ipfs/<CID>. Sem copiar e colar comandos curl, sem alternância de contexto.

Fluxos de trabalho reais que desbloqueia

Implantar um site estático no IPFS a partir do Claude Code:

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

Pipeline de metadados NFT:

Você: Crie uma pasta chamada "minha-coleção" e faça upload deste JSON de metadados
Claude: [chama ipfs_folders_create, depois ipfs_upload_json]
        → Pasta: minha-coleção
        → CID: QmAbc... — URL de metadados permanente pronta para seu contrato inteligente

Monitore o uso sem sair do editor:

Você: Estou perto do meu limite de armazenamento?
Claude: [chama ipfs_profile]
        → Plano: Bodhi, Armazenamento: 45.2 MB / 100 GB (0.04%)
Você: Mostre minha largura de banda esta semana
Claude: [chama ipfs_analytics com dias=7]
        → 2.3 MB de largura de banda, 45 solicitações em 3 dias

Pin conteúdo existente da rede:

Você: Pin o readme do IPFS em QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG
Claude: [chama ipfs_pin] → Pin iniciado! Status: pinning
Você: Está pronto?
Claude: [chama ipfs_pin_status] → Status: pinned, Tamanho: 0.008 MB

Solução de problemas (as três coisas que realmente dão errado)

• IPFS_NINJA_API_KEY variável de ambiente é necessária — o bloco env na sua configuração MCP está faltando a chave.
• Erro de API 402: armazenamento insuficiente — você atingiu o limite de armazenamento do seu plano. Atualize ou exclua arquivos não utilizados.
• Servidor não aparecendo em /mcp — você esqueceu de reiniciar o editor após adicionar o servidor. Também verifique se node --version é ≥ 18.