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

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

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:

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:

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:

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:

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)

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:

{
  "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:

{
  "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:

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

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

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