Servidor MCP

Use o IPFS Ninja diretamente de assistentes de IA para programacao como Claude Code, Cursor e Windsurf. Faca upload de arquivos, fixe CIDs, gerencie pastas e consulte seu uso — tudo a partir da sua conversa com a IA.

O que e MCP?

Model Context Protocol (MCP) e um padrao aberto para conectar assistentes de IA a ferramentas e fontes de dados externas. O servidor MCP do IPFS Ninja expoe 11 ferramentas que modelos de IA podem chamar durante conversas para interagir com sua conta no IPFS Ninja.

Instalacao

Pacote npm

@ipfs-ninja/mcp-server

Disponivel no npm. Nao precisa de instalacao global — executa via npx.

Pre-requisitos

• Node.js 18+ instalado
• Uma chave de API do IPFS Ninja (obtenha uma em Dashboard > API Keys)

Configuracao para Claude Code

Passo 1: Obtenha sua chave de API

1. Cadastre-se em ipfs.ninja (gratuito)
2. Acesse Dashboard > API Keys
3. Clique em Create API key e copie a chave completa (exibida apenas uma vez)

Passo 2: Adicione o servidor MCP

Execute este comando no seu 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

Ou adicione manualmente ao seu .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"
      }
    }
  }
}

Passo 3: Reinicie o Claude Code

Saia e reabra o Claude Code. Digite /mcp para verificar se o servidor IPFS Ninja esta conectado.

Passo 4: Comece a usar

Basta conversar com o Claude naturalmente:

Voce: Faca upload do meu README.md para o IPFS
Voce: Liste meus arquivos recentes
Voce: Quanto armazenamento estou usando?
Voce: Fixe bafyabc123... da rede IPFS
Voce: Crie uma pasta chamada "project-assets"

Configuracao para Cursor / Windsurf

Adicione nas suas configuracoes de MCP (Settings > MCP Servers):

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

Ferramentas Disponiveis

Operacoes de arquivo

Ferramenta	Descricao	Exemplo de prompt
ipfs_upload	Faz upload de conteudo de arquivo (base64 ou texto)	"Faca upload deste arquivo HTML para o IPFS"
ipfs_upload_json	Faz upload de um objeto JSON	"Armazene este config como JSON permanente no IPFS"
ipfs_list	Lista seus arquivos enviados	"Mostre meus uploads recentes"
ipfs_get	Obtem metadados do arquivo por CID	"Que tipo de arquivo e QmXyz...?"
ipfs_delete	Remove fixacao e exclui um arquivo	"Exclua QmXyz... da minha conta"

Fixacao (Pinning)

Ferramenta	Descricao	Exemplo de prompt
ipfs_pin	Fixa um CID existente da rede	"Fixe bafyabc... na minha conta"
ipfs_pin_status	Verifica o progresso da fixacao	"O bafyabc... ja terminou de fixar?"

Organizacao

Ferramenta	Descricao	Exemplo de prompt
ipfs_folders_list	Lista suas pastas	"Mostre minhas pastas"
ipfs_folders_create	Cria uma nova pasta	"Crie uma pasta chamada nft-metadata"

Conta

Ferramenta	Descricao	Exemplo de prompt
ipfs_profile	Obtem informacoes do plano, armazenamento e banda	"Quanto armazenamento estou usando?"
ipfs_analytics	Obtem estatisticas diarias de banda e arquivos	"Mostre meu uso de banda esta semana"

Exemplos de Fluxos de Trabalho

Publicar um site estatico

Voce: Faca upload do conteudo da minha pasta dist/ para o IPFS
Claude: [faz upload de cada arquivo, retorna CIDs]

Voce: Qual e o CID do index.html?
Claude: [chama ipfs_get]
     → QmXyz... — https://ipfs.ninja/ipfs/QmXyz...

Metadados NFT

Voce: Crie uma pasta chamada "my-collection" e faca upload deste JSON de metadados
Claude: [chama ipfs_folders_create, depois ipfs_upload_json]
     → Pasta: my-collection
     → CID: QmAbc... — URL de metadados permanente pronta para seu smart contract

Monitorar uso

Voce: Estou perto do meu limite de armazenamento?
Claude: [chama ipfs_profile]
     → Plano: Bodhi, Armazenamento: 45.2 MB / 100 GB (0.04%)
     → Voce tem bastante espaco.

Voce: Mostre minha banda esta semana
Claude: [chama ipfs_analytics com days=7]
     → 2.3 MB de banda, 45 requisicoes em 3 dias

Fixar conteudo da rede

Voce: Fixe o readme do IPFS em QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG
Claude: [chama ipfs_pin]
     → Fixacao iniciada! Status: fixando

Voce: Ja terminou?
Claude: [chama ipfs_pin_status]
     → Status: fixado, Tamanho: 0.008 MB

Solucao de Problemas

"IPFS_NINJA_API_KEY environment variable is required"

A chave de API nao esta configurada. Certifique-se de que a secao env na sua configuracao MCP tem a chave correta.

"API error 402: not enough storage"

Voce atingiu o limite de armazenamento do seu plano. Faca upgrade em ipfs.ninja/pricing ou exclua arquivos nao utilizados.

"API error 403: Forbidden"

Sua chave de API pode estar invalida ou expirada. Crie uma nova em Dashboard > API Keys.

O servidor nao aparece no /mcp

Certifique-se de que voce reiniciou o Claude Code apos adicionar o servidor MCP. Verifique se o Node.js 18+ esta instalado (node --version).