Pinata

Interaja com IPFS Público e Privado através da API da Pinata. Requer uma conta Pinata e chave de API.

Documentação

pinata-mcp

Um servidor Model Context Protocol (MCP) que fornece ao Claude acesso ao Pinata. Esta integração permite que o Claude interaja com IPFS público e privado através da API do Pinata.

Configuração

Pré-requisitos

Node.js 18+ instalado
Uma conta Pinata com uma chave de API (JWT)
Uma URL de Gateway Pinata

Instalação

A instalação dependerá de se você está usando Claude Code ou Claude Desktop.

Claude Code

Execute claude mcp add e siga as instruções com as seguintes informações:

Server Name: pinata
Server Scope: Project or Global
Server Command: npx
Command Arguments: pinata-mcp /path/to/allowed/directory
Environment Variables: PINATA_JWT=<YOUR_JWT>,GATEWAY_URL=example.mypinata.cloud

Claude Desktop

Adicione a seguinte configuração a claude_desktop_config.json:

{
  "mcpServers": {
    "pinata": {
      "command": "npx",
      "args": [
        "pinata-mcp",
        "/path/to/allowed/directory",
        "/another/allowed/directory"
      ],
      "env": {
        "PINATA_JWT": "<YOUR_JWT>",
        "GATEWAY_URL": "example.mypinata.cloud"
      }
    }
  }
}

Nota: Os argumentos de diretório são opcionais. Se não forem fornecidos, o servidor permitirá apenas acesso ao diretório de trabalho atual. Você pode especificar múltiplos diretórios para permitir acesso a arquivos de múltiplos locais.

Ferramentas Disponíveis

Autenticação

Ferramenta	Descrição
`testAuthentication`	Verifique se seu JWT Pinata é válido e está funcionando

Operações de Arquivo

Ferramenta	Descrição
`uploadFile`	Envie um arquivo para Pinata (IPFS público ou privado)
`searchFiles`	Pesquise arquivos por nome, CID ou tipo MIME
`getFileById`	Obtenha informações detalhadas do arquivo por ID
`updateFile`	Atualize metadados do arquivo (nome, chave-valores)
`deleteFile`	Exclua um arquivo do Pinata

Acesso ao Conteúdo

Ferramenta	Descrição
`createLink`	Crie um link de gateway para arquivos públicos ou privados
`createPrivateDownloadLink`	Gere um link de download temporário para arquivos privados
`fetchFromGateway`	Busque conteúdo do IPFS via gateway Pinata

Operações de Grupo

Ferramenta	Descrição
`listGroups`	Liste grupos com filtragem opcional
`createGroup`	Crie um novo grupo para organizar arquivos
`getGroup`	Obtenha detalhes do grupo por ID
`updateGroup`	Atualize informações do grupo
`deleteGroup`	Exclua um grupo
`addFileToGroup`	Adicione um arquivo a um grupo
`removeFileFromGroup`	Remova um arquivo de um grupo

Instruções de Pagamento x402

Ferramentas para monetização de conteúdo usando o protocolo x402:

Ferramenta	Descrição
`createPaymentInstruction`	Crie requisitos de pagamento para conteúdo restrito
`listPaymentInstructions`	Liste/filtre instruções de pagamento existentes
`getPaymentInstruction`	Obtenha detalhes de uma instrução de pagamento específica
`updatePaymentInstruction`	Modifique configurações de instrução de pagamento
`deletePaymentInstruction`	Remova uma instrução de pagamento
`listPaymentInstructionCids`	Liste CIDs associados a uma instrução de pagamento
`addCidToPaymentInstruction`	Associe um CID a uma instrução de pagamento
`removeCidFromPaymentInstruction`	Remova uma associação de CID

Assinaturas CID

Ferramentas para verificação criptográfica de conteúdo usando assinaturas EIP-712:

Ferramenta	Descrição
`addSignature`	Adicione uma assinatura criptográfica a um CID
`getSignature`	Obtenha detalhes da assinatura por CID
`deleteSignature`	Remova uma assinatura

URLs de Upload Assinadas

Ferramenta	Descrição
`createSignedUploadUrl`	Crie uma URL pré-assinada para uploads do lado do cliente

Pin por CID

Ferramenta	Descrição
`pinByCid`	Fixe um CID existente da rede IPFS
`queryPinRequests`	Consulte o status das solicitações de pin
`cancelPinRequest`	Cancele uma solicitação de pin pendente

Vetorizar (Busca IA/Semântica)

Ferramenta	Descrição
`vectorizeFile`	Vetorize um arquivo para busca semântica
`deleteFileVectors`	Exclua vetores de um arquivo
`queryVectors`	Consulte arquivos vetorizados usando busca semântica

Utilitários

Ferramenta	Descrição
`listAllowedDirectories`	Liste diretórios que o servidor pode acessar para operações de arquivo

Desenvolvimento Local

Para testar o servidor MCP localmente durante o desenvolvimento:

1. Clone e instale as dependências

git clone https://github.com/PinataCloud/pinata-mcp.git
cd pinata-mcp
npm install

2. Compile o projeto

npm run build

3. Configure as variáveis de ambiente

Crie um arquivo .env na raiz do projeto (opcional, você também pode passá-los na configuração MCP):

PINATA_JWT=your_pinata_jwt_here
GATEWAY_URL=your-gateway.mypinata.cloud

4. Configure o Claude para usar a compilação local

Claude Code

Execute claude mcp add com o caminho local:

Server Name: pinata-dev
Server Scope: Project
Server Command: node
Command Arguments: /path/to/pinata-mcp/dist/index.js /path/to/allowed/directory
Environment Variables: PINATA_JWT=<YOUR_JWT>,GATEWAY_URL=example.mypinata.cloud

Claude Desktop

Atualize claude_desktop_config.json para apontar para sua compilação local:

{
  "mcpServers": {
    "pinata-dev": {
      "command": "node",
      "args": [
        "/path/to/pinata-mcp/dist/index.js",
        "/path/to/allowed/directory"
      ],
      "env": {
        "PINATA_JWT": "<YOUR_JWT>",
        "GATEWAY_URL": "example.mypinata.cloud"
      }
    }
  }
}

5. Testando alterações

Após fazer alterações no código:

Recompile: npm run build
Reinicie o Claude Code ou o Claude Desktop para aplicar as alterações

Testando com o MCP Inspector

Use o MCP Inspector para testar o servidor:

Interface Web (depuração interativa)

npx @modelcontextprotocol/inspector \
  -e PINATA_JWT=your_jwt \
  -e GATEWAY_URL=your-gateway.mypinata.cloud \
  -- node dist/index.js

Isso abre uma interface de navegador onde você pode listar ferramentas interativamente, chamá-las com parâmetros e inspecionar respostas.

Modo CLI (para scripts/CI)

# List all available tools
npx @modelcontextprotocol/inspector --cli --method tools/list \
  -e PINATA_JWT=your_jwt \
  -e GATEWAY_URL=your-gateway.mypinata.cloud \
  -- node dist/index.js

# Call a specific tool
npx @modelcontextprotocol/inspector --cli --method tools/call \
  --tool-name testAuthentication \
  -e PINATA_JWT=your_jwt \
  -e GATEWAY_URL=your-gateway.mypinata.cloud \
  -- node dist/index.js

Exemplos de Prompts para Claude

Test my Pinata connection:
"Test my Pinata authentication to make sure everything is working"

Upload an image to Pinata:
"Upload this image to my Pinata account as a private file named 'My Example Image'"

Search for files:
"Search my Pinata account for all PNG files"

Create a group and add files:
"Create a new group called 'Project Assets' on Pinata, then find all my JSON files and add them to this group"

Fetch content from IPFS:
"Fetch the content with CID QmX... from IPFS"

Create a payment instruction for content monetization:
"Create a payment instruction called 'Premium Content' that requires 0.01 USDC on Base to access"

Pin an existing CID:
"Pin the CID bafkreih5aznjvttude6c3wbvqeebb6rlx5wkbzyppv7garjiubll2ceym4 to my account"

Vectorize files for AI search:
"Vectorize the file with ID abc123 so I can search it semantically"

Query vectorized content:
"Search my vectorized files in group xyz for 'machine learning concepts'"