MCP Banco Inter

🚀 MCP Banco Inter

A MCP (Model Context Protocol) server for integrating with the Banco Inter Empresas (PJ) API. It allows AI assistants (such as Claude, ChatGPT, Gemini, etc.) to query account balances, statements, issue and manage payment invoices — all through natural language.

✨ Features

Banking

• 💰 Query the balance of the current account.
• 📊 Query the statement for a specific period.
• 📄 Download the statement in PDF format.

Invoices (Bills)

• 📋 List issued invoices with filters (status, period).
• 🆕 Issue new payment invoices.
• ❌ Cancel invoices.
• 📊 Summary of invoices for a specific period.
• 📥 Download PDF of invoices.

📋 Prerequisites

• Node.js 18+ or Docker
• API credentials from Banco Inter (obtained from the Inter Developer Portal):
  • CLIENT_ID and CLIENT_SECRET
  • Digital certificate (.crt) and Private key (.key)
  • Current account number

⚙️ Configuration

1. Obtain your credentials from the Banco Inter Developer Portal.

2. Place the certificate files in a secure directory (e.g., ./certs/).

3. Create a .env file based on the .env.example:

# Mandatory credentials
CLIENT_ID=your_client_id
CLIENT_SECRET=your_client_secret
CERT_PATH=./certs/inter.crt
KEY_PATH=./certs/inter.key

# Account
X_CONTA_CORRENTE=123456789

# Local storage (generated PDFs)
STORAGE_PATH=./storage

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

# Network settings (only for streamable-http transport)
MCP_HOST=0.0.0.0
MCP_PORT=3000

# Sandbox (for testing)
INTER_IS_SANDBOX=true

⚠️ Important Note: Never commit the .env, .crt, and .key files to the repository. They are already in the .gitignore.

🚀 Installation and Usage

The server supports two transport modes:

1️⃣ Via npx — stdio mode (recommended for local clients)

This is the default mode. The MCP client starts the process and communicates via stdin/stdout:

CLIENT_ID=your_client_id \
CLIENT_SECRET=your_client_secret \
CERT_PATH=/absolute/path/inter.crt \
KEY_PATH=/absolute/path/inter.key \
X_CONTA_CORRENTE=your_account \
INTER_IS_SANDBOX=true \
npx -y samuelmoraesf/mcp-banco-inter

💡 In practice, you don't run this manually — the MCP client (Claude Desktop, Cursor, etc.) will execute the command automatically. See the configuration examples below.

2️⃣ Via npx — streamable-http mode (HTTP server)

To run as an HTTP server accessible to multiple clients:

CLIENT_ID=your_client_id \
CLIENT_SECRET=your_client_secret \
CERT_PATH=/absolute/path/inter.crt \
KEY_PATH=/absolute/path/inter.key \
X_CONTA_CORRENTE=your_account \
INTER_IS_SANDBOX=true \
MCP_TRANSPORT=streamable-http \
MCP_HOST=0.0.0.0 \
MCP_PORT=3000 \
npx -y samuelmoraesf/mcp-banco-inter

The server will be available at:

http://localhost:3000/mcp

3️⃣ Via Docker — streamable-http mode

The Docker container is already configured to run in streamable-http mode by default.

Local build:

docker build -t mcp-banco-inter .

docker run -d \
  --name mcp-banco-inter \
  -p 3000:3000 \
  -e CLIENT_ID=your_client_id \
  -e CLIENT_SECRET=your_client_secret \
  -e X_CONTA_CORRENTE=your_account \
  -e INTER_IS_SANDBOX=true \
  -v /absolute/path/certs:/app/certs \
  -e CERT_PATH=/app/certs/inter.crt \
  -e KEY_PATH=/app/certs/inter.key \
  mcp-banco-inter

Or directly from Docker Hub:

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

The container exposes the Streamable HTTP endpoint at http://localhost:3000/mcp.

4️⃣ Local installation (development)

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

🔌 Integration with MCP Clients

Claude Desktop (stdio)

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "banco-inter": {
      "command": "npx",
      "args": ["-y", "mcp-banco-inter"],
      "env": {
        "CLIENT_ID": "your_client_id",
        "CLIENT_SECRET": "your_client_secret",
        "CERT_PATH": "/absolute/path/inter.crt",
        "KEY_PATH": "/absolute/path/inter.key",
        "X_CONTA_CORRENTE": "your_account",
        "INTER_IS_SANDBOX": "true"
      }
    }
  }
}

Cursor / Windsurf / VS Code (stdio)

Add the following to the MCP configuration of your editor:

{
  "mcp": {
    "servers": {
      "banco-inter": {
        "command": "npx",
        "args": ["-y", "mcp-banco-inter"],
        "env": {
          "CLIENT_ID": "your_client_id",
          "CLIENT_SECRET": "your_client_secret",
          "CERT_PATH": "/absolute/path/inter.crt",
          "KEY_PATH": "/absolute/path/inter.key",
          "X_CONTA_CORRENTE": "your_account",
          "INTER_IS_SANDBOX": "true"
        }
      }
    }
  }
}

Remote clients (streamable-http)

For clients that connect via HTTP (including Docker), first start the server in streamable-http mode (see sections 2️⃣ or 3️⃣ above) and configure the client to connect to the endpoint:

http://localhost:3000/mcp

🛠️ Available Tools

🏗️ Architecture

src/
├── index.ts          # Entrypoint — configures the transport (stdio/HTTP)
├── server.ts         # Definition of the MCP server and registration of tools
├── inter-client.ts   # HTTP client for the Banco Inter API
└── types.ts          # TypeScript interfaces for requests/responses

🧪 Testing

# Unit tests
npm run test:unit

# Integration tests (requires .env configuration)
npm run test:integration

# All tests
npm test

📦 CI/CD

The project has automated pipelines via GitHub Actions:

• NPM Publish — Automatically publishes to NPM when creating tags v*.
• Docker Build & Push — Builds and publishes a multi-arch image (amd64/arm64) to Docker Hub when pushing to master or creating tags.

🔒 Security

• Communication with the Banco Inter API is done via mTLS (client digital certificate).
• The OAuth2 authentication token is stored only in memory and is automatically renewed.
• Sensitive files (.env, certificates, keys) are included in the .gitignore.