@gu-does-packages/pluggy-mcp

Servidor MCP para Pluggy — agregador Open Finance Brasil (ITP/TPP).

Baseado no @codespar/mcp-pluggy por CodeSpar, estendido com funcionalidades adicionais.

Licença: MIT — mantém os créditos ao trabalho original da CodeSpar.

Setup

bun install

Quick Start

Via npx (recomendado)

```bash
npx @gu-does-packages/pluggy-mcp

Claude Desktop

Adicione ao claude_desktop_config.json:

{
  "mcpServers": {
    "pluggy": {
      "command": "npx",
      "args": ["@gu-does-packages/pluggy-mcp"],
      "env": {
        "PLUGGY_CLIENT_ID": "seu-client-id",
        "PLUGGY_CLIENT_SECRET": "seu-client-secret"
      }
    }
  }
}

Cursor / VS Code

Mesma configuração em .cursor/mcp.json ou no JSON de MCP do VS Code.

Autenticação

Pluggy usa OAuth2 client-credentials. Obtenha suas credenciais no dashboard da Pluggy.

| Variável | Obrigatório | Descrição | |---|---|---| | PLUGGY_CLIENT_ID | sim | Client ID do dashboard | | PLUGGY_CLIENT_SECRET | sim | Client Secret do dashboard | | PLUGGY_API_BASE | não | URL base da API (default https://api.pluggy.ai) |

Sandbox

A Pluggy disponibiliza conectores sandbox (Pluggy Bank, BR · Pluggy Bank) que funcionam com o mesmo endpoint de produção. Use list_connectors com sandbox: true para listá-los.

Comandos

| Comando | Descrição | |---------|-----------| | bun run build | Compila para Node.js (dist/index.js) | | bun run start | Roda o servidor MCP (node dist/index.js) | | bun run test | Roda os testes automatizados | | bun run inspect | Abre o MCP Inspector (UI interativa no navegador) |

Créditos

Este projeto é um fork estendido do @codespar/mcp-pluggy (MIT), mantendo toda a funcionalidade original dos 18 tools MCP para a API Pluggy. Agradecimentos à CodeSpar pelo trabalho base.

Extensões em relação ao original

• list_investments — recupera todos os investimentos de um item (GET /investments)
• get_investment — recupera um investimento específico por ID (GET /investments/{id})
• list_investment_transactions — recupera todas as transações de um investimento (GET /investments/{id}/transactions)

Funcionalidades (18 tools)

| Tool | Endpoint Pluggy | Descrição | |---|---|---| | list_connectors | GET /connectors | Lista conectores (bancos) | | get_connector | GET /connectors/{id} | Detalhes de um conector | | list_categories | GET /categories | Taxonomia de categorias | | create_connect_token | POST /connect_token | Token para Pluggy Connect | | create_item | POST /items | Nova conexão bancária | | get_item | GET /items/{id} | Detalhes de uma conexão | | update_item | PATCH /items/{id} | Atualiza credenciais/sync | | delete_item | DELETE /items/{id} | Revoga conexão | | list_accounts | GET /accounts | Contas de um item | | get_account | GET /accounts/{id} | Detalhes de uma conta | | list_transactions | GET /transactions | Transações de uma conta | | get_transaction | GET /transactions/{id} | Detalhes de uma transação | | list_identities | GET /identity | Dados cadastrais (CPF, nome, endereço) | | list_investments | GET /investments | Investimentos de um item | | get_investment | GET /investments/{id} | Detalhes de um investimento | | list_investment_transactions | GET /investments/{id}/transactions | Transações de um investimento | | create_payment_intent | POST /payments/intents | Inicia intent de pagamento | | get_payment_intent | GET /payments/intents/{id} | Status do payment intent |

Publicação

bun run build
npm publish

npx @gu-does-packages/pluggy-mcp funciona em qualquer máquina com Node.js instalado.

Licença

MIT — veja LICENSE.