io.github.SamuelMoraesF/mcp-banco-inter

Official

by SamuelMoraesF · TypeScript

Servidor MCP para integração com o Banco Inter (PJ). Consulte saldos e gerencie cobranças.

Check account balances and manage billing for Banco Inter business accounts.

README.md8 KBView on GitHub

🏦 MCP Banco Inter

Um servidor MCP (Model Context Protocol) para integração com a API do Banco Inter Empresas (PJ).

Permite que assistentes de IA (como Claude, ChatGPT, Gemini, etc.) consultem saldos, extratos, emitam e gerenciem boletos de cobrança — tudo via linguagem natural.

✨ Funcionalidades

Banking

💰 Consulta de saldo da conta corrente
📊 Consulta de extrato por período
📄 Download de extrato em PDF

Cobranças (Boletos)

📋 Listar cobranças emitidas com filtros (situação, período)
🆕 Emitir novos boletos de cobrança
❌ Cancelar cobranças
📊 Sumário de cobranças por período
📥 Baixar PDF de boletos

📋 Pré-requisitos

Node.js 18+ ou Docker
Credenciais de API do Banco Inter (obtidas no Portal do Desenvolvedor Inter):
- CLIENT_ID e CLIENT_SECRET
- Certificado digital (.crt) e Chave Privada (.key)
- Número da Conta Corrente

⚙️ Configuração

1. Obtenha suas credenciais no Portal do Desenvolvedor do Banco Inter

2. Coloque os arquivos de certificado em um diretório seguro (ex.: ./certs/)

3. Crie um arquivo .env baseado no .env.example:

env

# Credenciais obrigatórias
CLIENT_ID=your_client_id
CLIENT_SECRET=your_client_secret
CERT_PATH=./certs/inter.crt
KEY_PATH=./certs/inter.key

# Conta
X_CONTA_CORRENTE=123456789

# Armazenamento local (PDFs gerados)
STORAGE_PATH=./storage

# Transporte MCP: "stdio" | "streamable-http"
MCP_TRANSPORT=stdio

# Configurações de rede (apenas para transporte streamable-http)
MCP_HOST=0.0.0.0
MCP_PORT=3000

# Sandbox (para testes)
INTER_IS_SANDBOX=true

⚠️ Importante: Nunca comite os arquivos .env, .crt e .key no repositório. Eles já estão no .gitignore.

🚀 Instalação e Uso

O servidor suporta dois modos de transporte:

Transporte	Uso	Ideal para
`stdio`	Comunicação via stdin/stdout	Clientes locais (Claude Desktop, Cursor, etc.)
`streamable-http`	Servidor HTTP com Streamable HTTP	Clientes remotos, Docker, múltiplos clientes

1️⃣ Via `npx` — Modo `stdio` (recomendado para clientes locais)

O modo padrão. O cliente MCP inicia o processo e se comunica via stdin/stdout:

bash

CLIENT_ID=seu_client_id \
CLIENT_SECRET=seu_client_secret \
CERT_PATH=/caminho/absoluto/inter.crt \
KEY_PATH=/caminho/absoluto/inter.key \
X_CONTA_CORRENTE=sua_conta \
INTER_IS_SANDBOX=true \
npx -y samuelmoraesf/mcp-banco-inter

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

2️⃣ Via `npx` — Modo `streamable-http` (servidor HTTP)

Para rodar como servidor HTTP acessível por múltiplos clientes:

bash

CLIENT_ID=seu_client_id \
CLIENT_SECRET=seu_client_secret \
CERT_PATH=/caminho/absoluto/inter.crt \
KEY_PATH=/caminho/absoluto/inter.key \
X_CONTA_CORRENTE=sua_conta \
INTER_IS_SANDBOX=true \
MCP_TRANSPORT=streamable-http \
MCP_HOST=0.0.0.0 \
MCP_PORT=3000 \
npx -y samuelmoraesf/mcp-banco-inter

O servidor estará disponível em:

code

http://localhost:3000/mcp

3️⃣ Via Docker — Modo `streamable-http`

O container Docker já vem configurado para rodar em modo streamable-http por padrão.

Build local:

bash

docker build -t mcp-banco-inter .

docker run -d \
  --name mcp-banco-inter \
  -p 3000:3000 \
  -e CLIENT_ID=seu_client_id \
  -e CLIENT_SECRET=seu_client_secret \
  -e X_CONTA_CORRENTE=sua_conta \
  -e INTER_IS_SANDBOX=true \
  -v /caminho/absoluto/certs:/app/certs \
  -e CERT_PATH=/app/certs/inter.crt \
  -e KEY_PATH=/app/certs/inter.key \
  mcp-banco-inter

Ou diretamente do Docker Hub:

bash

docker run -d \
  --name mcp-banco-inter \
  -p 3000:3000 \
  --env-file .env \
  -v ./certs:/app/certs \
  samuelmoraesf/mcp-banco-inter:latest

O container expõe o endpoint Streamable HTTP em http://localhost:3000/mcp.

4️⃣ Instalação local (desenvolvimento)

bash

git clone https://github.com/samuelmoraesf/mcp-banco-inter.git
cd mcp-banco-inter
npm install
npm run build
npm start

🔌 Integração com Clientes MCP

Claude Desktop (stdio)

Adicione ao seu claude_desktop_config.json:

json

{
  "mcpServers": {
    "banco-inter": {
      "command": "npx",
      "args": ["-y", "mcp-banco-inter"],
      "env": {
        "CLIENT_ID": "seu_client_id",
        "CLIENT_SECRET": "seu_client_secret",
        "CERT_PATH": "/caminho/absoluto/inter.crt",
        "KEY_PATH": "/caminho/absoluto/inter.key",
        "X_CONTA_CORRENTE": "sua_conta",
        "INTER_IS_SANDBOX": "true"
      }
    }
  }
}

Cursor / Windsurf / VS Code (stdio)

Na configuração MCP do seu editor, adicione:

json

{
  "mcp": {
    "servers": {
      "banco-inter": {
        "command": "npx",
        "args": ["-y", "mcp-banco-inter"],
        "env": {
          "CLIENT_ID": "seu_client_id",
          "CLIENT_SECRET": "seu_client_secret",
          "CERT_PATH": "/caminho/absoluto/inter.crt",
          "KEY_PATH": "/caminho/absoluto/inter.key",
          "X_CONTA_CORRENTE": "sua_conta",
          "INTER_IS_SANDBOX": "true"
        }
      }
    }
  }
}

Clientes remotos (streamable-http)

Para 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:

code

http://localhost:3000/mcp

🛠️ Ferramentas Disponíveis

Ferramenta	Descrição	Parâmetros
`consultar_saldo`	Retorna o saldo disponível da conta.	—
`consultar_extrato`	Retorna as movimentações em um período.	`dataInicial`, `dataFinal`
`baixar_pdf_extrato`	Gera e salva o PDF do extrato.	`dataInicial`, `dataFinal`
`listar_boletos`	Lista cobranças por período e situação.	`dataInicial`, `dataFinal`, `situacao?`
`emitir_boleto`	Cria um novo boleto de cobrança.	`seuNumero`, `valorNominal`, `dataVencimento`, `pagador`
`baixar_pdf_boleto`	Gera e salva o PDF de um boleto.	`codigoSolicitacao`
`cancelar_boleto`	Cancela uma cobrança existente.	`codigoSolicitacao`, `motivo`
`sumario_boletos`	Resumo quantitativo de cobranças por período.	`dataInicial`, `dataFinal`

🏗️ Arquitetura

code

src/
├── index.ts          # Entrypoint — configura transporte (stdio/HTTP)
├── server.ts         # Definição do servidor MCP e registro das tools
├── inter-client.ts   # Cliente HTTP para a API do Banco Inter
└── types.ts          # Interfaces TypeScript das requisições/respostas

Módulo	Responsabilidade
`index.ts`	Carrega variáveis de ambiente, inicializa o `InterClient` e o `InterMcpServer`, e configura o transporte (`stdio` ou `Streamable HTTP`).
`server.ts`	Registra as ferramentas MCP e delega chamadas ao `InterClient`.
`inter-client.ts`	Autenticação OAuth2 com mTLS, cache de token, e todas as chamadas REST à API Inter (Banking v2 e Cobrança v3).
`types.ts`	Tipagem completa de todas as interfaces usadas nas requisições e respostas da API.

🧪 Testes

bash

# Testes unitários
npm run test:unit

# Testes de integração (requer .env configurado)
npm run test:integration

# Todos os testes
npm test

📦 CI/CD

O projeto possui pipelines automatizados via GitHub Actions:

NPM Publish — Publica automaticamente no NPM ao criar tags v*.
Docker Build & Push — Builda e publica imagem multi-arch (amd64/arm64) no Docker Hub ao fazer push em master ou ao criar tags.

🔒 Segurança

A comunicação com a API do Banco Inter é feita via mTLS (certificado digital do cliente).
O token de autenticação OAuth2 é armazenado apenas em memória e renovado automaticamente.
Os arquivos sensíveis (.env, certificados, chaves) estão incluídos no .gitignore.

Install

Configuration

Environment variables

CLIENT_IDrequiredsecret

ID do cliente obtido no Portal do Desenvolvedor Inter

CLIENT_SECRETrequiredsecret

Secret do cliente obtido no Portal do Desenvolvedor Inter

CERT_PATHrequired

Caminho absoluto para o arquivo de certificado (.crt)

KEY_PATHrequired

Caminho absoluto para o arquivo de chave privada (.key)

X_CONTA_CORRENTE

Número da conta corrente

STORAGE_PATHdefault ./storage

Caminho para salvamento dos PDFs

INTER_IS_SANDBOXdefault false

Habilitar modo sandbox

MCP_PORTdefault 3000

Porta do servidor HTTP

MCP_HOSTdefault 0.0.0.0

Host do servidor HTTP

claude_desktop_config.json

{
  "mcpServers": {
    "mcp-banco-inter": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-banco-inter@1.0.1"
      ],
      "env": {
        "CLIENT_ID": "<YOUR_CLIENT_ID>",
        "CLIENT_SECRET": "<YOUR_CLIENT_SECRET>",
        "CERT_PATH": "<YOUR_CERT_PATH>",
        "KEY_PATH": "<YOUR_KEY_PATH>",
        "X_CONTA_CORRENTE": "<YOUR_X_CONTA_CORRENTE>",
        "STORAGE_PATH": "./storage",
        "INTER_IS_SANDBOX": "false"
      }
    }
  }
}

🏦 MCP Banco Inter

✨ Funcionalidades

Banking

Cobranças (Boletos)

📋 Pré-requisitos

⚙️ Configuração

🚀 Instalação e Uso

1️⃣ Via npx — Modo stdio (recomendado para clientes locais)

2️⃣ Via npx — Modo streamable-http (servidor HTTP)

3️⃣ Via Docker — Modo streamable-http

4️⃣ Instalação local (desenvolvimento)

🔌 Integração com Clientes MCP

Claude Desktop (stdio)

Cursor / Windsurf / VS Code (stdio)

Clientes remotos (streamable-http)

🛠️ Ferramentas Disponíveis

🏗️ Arquitetura

🧪 Testes

📦 CI/CD

🔒 Segurança

Install

Configuration

1️⃣ Via `npx` — Modo `stdio` (recomendado para clientes locais)

2️⃣ Via `npx` — Modo `streamable-http` (servidor HTTP)

3️⃣ Via Docker — Modo `streamable-http`