Servidor MCP

Utilize o IPFS Ninja diretamente a partir de assistentes de IA para programacao como Claude Code, Cursor e Windsurf. Carregue ficheiros, fixe CIDs, gira pastas e consulte a sua utilizacao — tudo a partir da sua conversa com a IA.

O que e o MCP?

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

Instalacao

Pacote npm

@ipfs-ninja/mcp-server

Disponivel no npm. Nao necessita 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 a sua chave de API

1. Registe-se em ipfs.ninja (gratuito)
2. Aceda a Dashboard > API Keys
3. Clique em Create API key e copie a chave completa (apresentada 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. Escreva /mcp para verificar se o servidor IPFS Ninja esta ligado.

Passo 4: Comece a utilizar

Basta conversar com o Claude naturalmente:

Voce: Carregue o meu README.md para o IPFS
Voce: Liste os meus ficheiros recentes
Voce: Quanto armazenamento estou a utilizar?
Voce: Fixe bafyabc123... da rede IPFS
Voce: Crie uma pasta chamada "project-assets"

Configuracao para Cursor / Windsurf

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

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

Ferramentas Disponiveis

Operacoes de ficheiro

Ferramenta	Descricao	Exemplo de prompt
ipfs_upload	Carrega conteudo de ficheiro (base64 ou texto)	"Carregue este ficheiro HTML para o IPFS"
ipfs_upload_json	Carrega um objeto JSON	"Armazene este config como JSON permanente no IPFS"
ipfs_list	Lista os seus ficheiros carregados	"Mostre os meus carregamentos recentes"
ipfs_get	Obtem metadados do ficheiro por CID	"Que tipo de ficheiro e QmXyz...?"
ipfs_delete	Remove fixacao e elimina um ficheiro	"Elimine 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 as suas pastas	"Mostre as 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 largura de banda	"Quanto armazenamento estou a utilizar?"
ipfs_analytics	Obtem estatisticas diarias de largura de banda e ficheiros	"Mostre a minha utilizacao de largura de banda esta semana"

Exemplos de Fluxos de Trabalho

Publicar um site estatico

Voce: Carregue o conteudo da minha pasta dist/ para o IPFS
Claude: [carrega cada ficheiro, devolve CIDs]

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

Metadados NFT

Voce: Crie uma pasta chamada "my-collection" e carregue este JSON de metadados
Claude: [invoca ipfs_folders_create, depois ipfs_upload_json]
     → Pasta: my-collection
     → CID: QmAbc... — URL de metadados permanente pronto para o seu smart contract

Monitorizar utilizacao

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

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

Fixar conteudo da rede

Voce: Fixe o readme do IPFS em QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG
Claude: [invoca ipfs_pin]
     → Fixacao iniciada! Estado: a fixar

Voce: Ja terminou?
Claude: [invoca ipfs_pin_status]
     → Estado: fixado, Tamanho: 0.008 MB

Resolucao de Problemas

"IPFS_NINJA_API_KEY environment variable is required"

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

"API error 402: not enough storage"

Atingiu o limite de armazenamento do seu plano. Faca upgrade em ipfs.ninja/pricing ou elimine ficheiros nao utilizados.

"API error 403: Forbidden"

A 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 reiniciou o Claude Code apos adicionar o servidor MCP. Verifique se o Node.js 18+ esta instalado (node --version).