Server MCP

Usa IPFS Ninja direttamente dagli assistenti di codifica AI come Claude Code, Cursor e Windsurf. Carica file, pinna CID, gestisci cartelle e controlla l'utilizzo — tutto dalla tua conversazione AI.

Cos'e MCP?

Model Context Protocol (MCP) e uno standard aperto per connettere assistenti AI a strumenti e fonti di dati esterne. Il server MCP di IPFS Ninja espone 11 strumenti che i modelli AI possono chiamare durante le conversazioni per interagire con il tuo account IPFS Ninja.

Installazione

Pacchetto npm

@ipfs-ninja/mcp-server

Disponibile su npm. Non serve installazione globale — si esegue tramite npx.

Prerequisiti

• Node.js 18+ installato
• Una chiave API IPFS Ninja (ottienila su Dashboard > API Keys)

Configurazione per Claude Code

Passo 1: Ottieni la tua chiave API

1. Registrati su ipfs.ninja (gratuito)
2. Vai su Dashboard > API Keys
3. Clicca Create API key e copia la chiave completa (mostrata una sola volta)

Passo 2: Aggiungi il server MCP

Esegui questo comando nel tuo terminale:

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

Oppure aggiungi manualmente al tuo .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: Riavvia Claude Code

Esci e riapri Claude Code. Digita /mcp per verificare che il server IPFS Ninja sia connesso.

Passo 4: Inizia a usarlo

Parla con Claude in modo naturale:

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"

Configurazione per Cursor / Windsurf

Aggiungi alle impostazioni MCP (Settings > MCP Servers):

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

Strumenti Disponibili

Operazioni sui file

Strumento	Descrizione	Esempio di prompt
ipfs_upload	Carica contenuto di un file (base64 o testo)	"Carica questo file HTML su IPFS"
ipfs_upload_json	Carica un oggetto JSON	"Salva questa config come JSON permanente su IPFS"
ipfs_list	Elenca i tuoi file caricati	"Mostra i miei caricamenti recenti"
ipfs_get	Ottieni i metadati di un file tramite CID	"Che tipo di file e QmXyz...?"
ipfs_delete	Rimuovi il pin ed elimina un file	"Elimina QmXyz... dal mio account"

Pinning

Strumento	Descrizione	Esempio di prompt
ipfs_pin	Pinna un CID esistente dalla rete	"Pinna bafyabc... sul mio account"
ipfs_pin_status	Controlla lo stato del pinning	"bafyabc... ha finito il pinning?"

Organizzazione

Strumento	Descrizione	Esempio di prompt
ipfs_folders_list	Elenca le tue cartelle	"Mostra le mie cartelle"
ipfs_folders_create	Crea una nuova cartella	"Crea una cartella chiamata nft-metadata"

Account

Strumento	Descrizione	Esempio di prompt
ipfs_profile	Ottieni info su piano, spazio e banda	"Quanto spazio sto usando?"
ipfs_analytics	Ottieni statistiche giornaliere su banda e file	"Mostra il mio utilizzo di banda questa settimana"

Esempi di Flussi di Lavoro

Deploy di un sito statico

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...

Metadati NFT

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

Monitorare l'utilizzo

You: Am I close to my storage limit?
Claude: [calls ipfs_profile]
     → Plan: Bodhi, Storage: 45.2 MB / 100 GB (0.04%)
     → You have plenty of room.

You: Show my bandwidth this week
Claude: [calls ipfs_analytics with days=7]
     → 2.3 MB bandwidth, 45 requests across 3 days

Pinnare contenuto dalla rete

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

Risoluzione dei Problemi

"IPFS_NINJA_API_KEY environment variable is required"

La chiave API non e impostata. Assicurati che la sezione env nella configurazione MCP contenga la chiave corretta.

"API error 402: not enough storage"

Hai raggiunto il limite di spazio del tuo piano. Fai l'upgrade su ipfs.ninja/pricing o elimina i file inutilizzati.

"API error 403: Forbidden"

La tua chiave API potrebbe essere invalida o scaduta. Creane una nuova su Dashboard > API Keys.

Il server non appare in /mcp

Assicurati di aver riavviato Claude Code dopo aver aggiunto il server MCP. Verifica che Node.js 18+ sia installato (node --version).