{
  "markdown": "# 🏦 MCP Banco Inter\n\n[![NPM Version](https://img.shields.io/npm/v/samuelmoraesf/mcp-banco-inter)](https://www.npmjs.com/package/samuelmoraesf/mcp-banco-inter)\n[![Docker Image](https://img.shields.io/docker/v/samuelmoraesf/mcp-banco-inter?label=docker)](https://hub.docker.com/r/samuelmoraesf/mcp-banco-inter)\n[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)\n\nUm servidor **[MCP (Model Context Protocol)](https://modelcontextprotocol.io/)** para integração com a API do **Banco Inter Empresas (PJ)**.\n\nPermite que assistentes de IA (como Claude, ChatGPT, Gemini, etc.) consultem saldos, extratos, emitam e gerenciem boletos de cobrança — tudo via linguagem natural.\n\n---\n\n## ✨ Funcionalidades\n\n### Banking\n- 💰 Consulta de **saldo** da conta corrente\n- 📊 Consulta de **extrato** por período\n- 📄 Download de **extrato em PDF**\n\n### Cobranças (Boletos)\n- 📋 **Listar** cobranças emitidas com filtros (situação, período)\n- 🆕 **Emitir** novos boletos de cobrança\n- ❌ **Cancelar** cobranças\n- 📊 **Sumário** de cobranças por período\n- 📥 **Baixar PDF** de boletos\n\n---\n\n## 📋 Pré-requisitos\n\n- **Node.js 18+** ou **Docker**\n- Credenciais de API do Banco Inter (obtidas no [Portal do Desenvolvedor Inter](https://developers.inter.co/)):\n  - `CLIENT_ID` e `CLIENT_SECRET`\n  - Certificado digital (`.crt`) e Chave Privada (`.key`)\n  - Número da Conta Corrente\n\n---\n\n## ⚙️ Configuração\n\n**1.** Obtenha suas credenciais no [Portal do Desenvolvedor do Banco Inter](https://developers.inter.co/)\n\n**2.** Coloque os arquivos de certificado em um diretório seguro (ex.: `./certs/`)\n\n**3.** Crie um arquivo `.env` baseado no `.env.example`:\n\n```env\n# Credenciais obrigatórias\nCLIENT_ID=your_client_id\nCLIENT_SECRET=your_client_secret\nCERT_PATH=./certs/inter.crt\nKEY_PATH=./certs/inter.key\n\n# Conta\nX_CONTA_CORRENTE=123456789\n\n# Armazenamento local (PDFs gerados)\nSTORAGE_PATH=./storage\n\n# Transporte MCP: \"stdio\" | \"streamable-http\"\nMCP_TRANSPORT=stdio\n\n# Configurações de rede (apenas para transporte streamable-http)\nMCP_HOST=0.0.0.0\nMCP_PORT=3000\n\n# Sandbox (para testes)\nINTER_IS_SANDBOX=true\n```\n\n> ⚠️ **Importante:** Nunca comite os arquivos `.env`, `.crt` e `.key` no repositório. Eles já estão no `.gitignore`.\n\n---\n\n## 🚀 Instalação e Uso\n\nO servidor suporta dois modos de transporte:\n\n| Transporte | Uso | Ideal para |\n|---|---|---|\n| **`stdio`** | Comunicação via stdin/stdout | Clientes locais (Claude Desktop, Cursor, etc.) |\n| **`streamable-http`** | Servidor HTTP com Streamable HTTP | Clientes remotos, Docker, múltiplos clientes |\n\n---\n\n### 1️⃣ Via `npx` — Modo `stdio` (recomendado para clientes locais)\n\nO modo padrão. O cliente MCP inicia o processo e se comunica via stdin/stdout:\n\n```bash\nCLIENT_ID=seu_client_id \\\nCLIENT_SECRET=seu_client_secret \\\nCERT_PATH=/caminho/absoluto/inter.crt \\\nKEY_PATH=/caminho/absoluto/inter.key \\\nX_CONTA_CORRENTE=sua_conta \\\nINTER_IS_SANDBOX=true \\\nnpx -y samuelmoraesf/mcp-banco-inter\n```\n\n> 💡 Na prática, você não roda manualmente — o cliente MCP (Claude Desktop, Cursor, etc.) executará o comando automaticamente. Veja os exemplos de configuração abaixo.\n\n---\n\n### 2️⃣ Via `npx` — Modo `streamable-http` (servidor HTTP)\n\nPara rodar como servidor HTTP acessível por múltiplos clientes:\n\n```bash\nCLIENT_ID=seu_client_id \\\nCLIENT_SECRET=seu_client_secret \\\nCERT_PATH=/caminho/absoluto/inter.crt \\\nKEY_PATH=/caminho/absoluto/inter.key \\\nX_CONTA_CORRENTE=sua_conta \\\nINTER_IS_SANDBOX=true \\\nMCP_TRANSPORT=streamable-http \\\nMCP_HOST=0.0.0.0 \\\nMCP_PORT=3000 \\\nnpx -y samuelmoraesf/mcp-banco-inter\n```\n\nO servidor estará disponível em:\n```\nhttp://localhost:3000/mcp\n```\n\n---\n\n### 3️⃣ Via Docker — Modo `streamable-http`\n\nO container Docker já vem configurado para rodar em modo `streamable-http` por padrão.\n\n**Build local:**\n\n```bash\ndocker build -t mcp-banco-inter .\n\ndocker run -d \\\n  --name mcp-banco-inter \\\n  -p 3000:3000 \\\n  -e CLIENT_ID=seu_client_id \\\n  -e CLIENT_SECRET=seu_client_secret \\\n  -e X_CONTA_CORRENTE=sua_conta \\\n  -e INTER_IS_SANDBOX=true \\\n  -v /caminho/absoluto/certs:/app/certs \\\n  -e CERT_PATH=/app/certs/inter.crt \\\n  -e KEY_PATH=/app/certs/inter.key \\\n  mcp-banco-inter\n```\n\n**Ou diretamente do Docker Hub:**\n\n```bash\ndocker run -d \\\n  --name mcp-banco-inter \\\n  -p 3000:3000 \\\n  --env-file .env \\\n  -v ./certs:/app/certs \\\n  samuelmoraesf/mcp-banco-inter:latest\n```\n\n> O container expõe o endpoint Streamable HTTP em `http://localhost:3000/mcp`.\n\n---\n\n### 4️⃣ Instalação local (desenvolvimento)\n\n```bash\ngit clone https://github.com/samuelmoraesf/mcp-banco-inter.git\ncd mcp-banco-inter\nnpm install\nnpm run build\nnpm start\n```\n\n---\n\n## 🔌 Integração com Clientes MCP\n\n### Claude Desktop (stdio)\n\nAdicione ao seu `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"banco-inter\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-banco-inter\"],\n      \"env\": {\n        \"CLIENT_ID\": \"seu_client_id\",\n        \"CLIENT_SECRET\": \"seu_client_secret\",\n        \"CERT_PATH\": \"/caminho/absoluto/inter.crt\",\n        \"KEY_PATH\": \"/caminho/absoluto/inter.key\",\n        \"X_CONTA_CORRENTE\": \"sua_conta\",\n        \"INTER_IS_SANDBOX\": \"true\"\n      }\n    }\n  }\n}\n```\n\n### Cursor / Windsurf / VS Code (stdio)\n\nNa configuração MCP do seu editor, adicione:\n\n```json\n{\n  \"mcp\": {\n    \"servers\": {\n      \"banco-inter\": {\n        \"command\": \"npx\",\n        \"args\": [\"-y\", \"mcp-banco-inter\"],\n        \"env\": {\n          \"CLIENT_ID\": \"seu_client_id\",\n          \"CLIENT_SECRET\": \"seu_client_secret\",\n          \"CERT_PATH\": \"/caminho/absoluto/inter.crt\",\n          \"KEY_PATH\": \"/caminho/absoluto/inter.key\",\n          \"X_CONTA_CORRENTE\": \"sua_conta\",\n          \"INTER_IS_SANDBOX\": \"true\"\n        }\n      }\n    }\n  }\n}\n```\n\n### Clientes remotos (streamable-http)\n\nPara clientes que se conectam via HTTP (incluindo Docker), primeiro inicie o servidor em modo `streamable-http` (veja seções 2️⃣ ou 3️⃣ acima) e configure o cliente para conectar ao endpoint:\n\n```\nhttp://localhost:3000/mcp\n```\n\n---\n\n## 🛠️ Ferramentas Disponíveis\n\n| Ferramenta | Descrição | Parâmetros |\n|---|---|---|\n| `consultar_saldo` | Retorna o saldo disponível da conta. | — |\n| `consultar_extrato` | Retorna as movimentações em um período. | `dataInicial`, `dataFinal` |\n| `baixar_pdf_extrato` | Gera e salva o PDF do extrato. | `dataInicial`, `dataFinal` |\n| `listar_boletos` | Lista cobranças por período e situação. | `dataInicial`, `dataFinal`, `situacao?` |\n| `emitir_boleto` | Cria um novo boleto de cobrança. | `seuNumero`, `valorNominal`, `dataVencimento`, `pagador` |\n| `baixar_pdf_boleto` | Gera e salva o PDF de um boleto. | `codigoSolicitacao` |\n| `cancelar_boleto` | Cancela uma cobrança existente. | `codigoSolicitacao`, `motivo` |\n| `sumario_boletos` | Resumo quantitativo de cobranças por período. | `dataInicial`, `dataFinal` |\n\n---\n\n## 🏗️ Arquitetura\n\n```\nsrc/\n├── index.ts          # Entrypoint — configura transporte (stdio/HTTP)\n├── server.ts         # Definição do servidor MCP e registro das tools\n├── inter-client.ts   # Cliente HTTP para a API do Banco Inter\n└── types.ts          # Interfaces TypeScript das requisições/respostas\n```\n\n| Módulo | Responsabilidade |\n|---|---|\n| **`index.ts`** | Carrega variáveis de ambiente, inicializa o `InterClient` e o `InterMcpServer`, e configura o transporte (`stdio` ou `Streamable HTTP`). |\n| **`server.ts`** | Registra as ferramentas MCP e delega chamadas ao `InterClient`. |\n| **`inter-client.ts`** | Autenticação OAuth2 com mTLS, cache de token, e todas as chamadas REST à API Inter (Banking v2 e Cobrança v3). |\n| **`types.ts`** | Tipagem completa de todas as interfaces usadas nas requisições e respostas da API. |\n\n---\n\n## 🧪 Testes\n\n```bash\n# Testes unitários\nnpm run test:unit\n\n# Testes de integração (requer .env configurado)\nnpm run test:integration\n\n# Todos os testes\nnpm test\n```\n\n---\n\n## 📦 CI/CD\n\nO projeto possui pipelines automatizados via **GitHub Actions**:\n\n- **NPM Publish** — Publica automaticamente no NPM ao criar tags `v*`.\n- **Docker Build & Push** — Builda e publica imagem multi-arch (`amd64`/`arm64`) no Docker Hub ao fazer push em `master` ou ao criar tags.\n\n---\n\n## 🔒 Segurança\n\n- A comunicação com a API do Banco Inter é feita via **mTLS** (certificado digital do cliente).\n- O token de autenticação OAuth2 é armazenado **apenas em memória** e renovado automaticamente.\n- Os arquivos sensíveis (`.env`, certificados, chaves) estão incluídos no `.gitignore`.\n",
  "bytes": 8434,
  "sha": "597620e64eb4d67ae3903856644c5ab137c1d9c5205ab9128c289dcc8ddc9547",
  "repo_slug": "samuelmoraesf/mcp-banco-inter",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_samuelmoraesf_mcp_banco_inter_b07820dc/readme"
}