MCP Banco Inter

🚀 🏦 MCP Banco Inter

这是一个 MCP (模型上下文协议) 服务器，用于与 巴西银行Inter Empresas (PJ) 的API集成。它允许人工智能助手（如Claude、ChatGPT、Gemini等）通过自然语言查询账户余额、交易明细，开具和管理账单。

✨ 主要特性

银行服务

• 💰 查询活期账户的 余额
• 📊 按时间段查询 交易明细
• 📄 下载 PDF格式的交易明细

账单管理

• 📋 列出 已开具的账单，并可按状态和时间段进行筛选
• 🆕 开具 新的账单
• ❌ 取消 账单
• 📊 按时间段统计 账单汇总信息
• 📥 下载 账单的PDF文件

📦 安装指南

前置要求

• Node.js 18+ 或 Docker
• 从 巴西银行开发者门户 获取的API凭证：
  • CLIENT_ID 和 CLIENT_SECRET
  • 数字证书 (.crt) 和私钥 (.key)
  • 活期账户号码

配置步骤

1. 从 巴西银行开发者门户 获取凭证。

2. 将证书文件存放在安全的目录中（例如：./certs/）。

3. 根据 .env.example 创建 .env 文件：

# 必需的凭证
CLIENT_ID=your_client_id
CLIENT_SECRET=your_client_secret
CERT_PATH=./certs/inter.crt
KEY_PATH=./certs/inter.key

# 账户信息
X_CONTA_CORRENTE=123456789

# 本地存储（生成的PDF文件）
STORAGE_PATH=./storage

# MCP传输方式："stdio" | "streamable-http"
MCP_TRANSPORT=stdio

# 网络配置（仅适用于 streamable-http 传输方式）
MCP_HOST=0.0.0.0
MCP_PORT=3000

# 沙盒环境（用于测试）
INTER_IS_SANDBOX=true

⚠️ 重要提示：

切勿将 .env、.crt 和 .key 文件提交到代码仓库，这些文件已包含在 .gitignore 中。

安装方式

本服务器支持两种传输模式：

1️⃣ 通过 npx 运行 — stdio 模式（推荐用于本地客户端）

这是默认模式，MCP客户端启动进程并通过标准输入/输出进行通信：

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

💡 使用建议：

实际上，你无需手动运行该命令，MCP客户端（如Claude Desktop、Cursor等）会自动执行。具体配置示例如下。

2️⃣ 通过 npx 运行 — streamable-http 模式（HTTP服务器）

以HTTP服务器模式运行，供多个客户端访问：

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

服务器将在以下地址可用：

http://localhost:3000/mcp

3️⃣ 通过 Docker 运行 — streamable-http 模式

Docker容器默认配置为以 streamable-http 模式运行。

本地构建：

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

或者直接从 Docker Hub 拉取：

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

容器将在 http://localhost:3000/mcp 暴露Streamable HTTP端点。

4️⃣ 本地安装（开发环境）

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

💻 使用示例

与 MCP 客户端集成

Claude Desktop (stdio)

在 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)

在编辑器的MCP配置中添加以下内容：

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

远程客户端 (streamable-http)

对于通过HTTP连接的客户端（包括Docker），首先以 streamable-http 模式启动服务器（见上述第2️⃣ 或 3️⃣ 部分），然后将客户端配置为连接到以下端点：

http://localhost:3000/mcp

📚 详细文档

可用工具

架构说明

src/
├── index.ts          # 入口文件 — 配置传输方式 (stdio/HTTP)
├── server.ts         # MCP服务器的定义和工具注册
├── inter-client.ts   # 用于巴西银行API的HTTP客户端
└── types.ts          # 请求/响应的TypeScript接口

测试命令

# 单元测试
npm run test:unit

# 集成测试（需要配置 .env 文件）
npm run test:integration

# 运行所有测试
npm test

CI/CD

本项目通过 GitHub Actions 实现了自动化管道：

• NPM发布 — 在创建 v* 标签时自动发布到NPM。
• Docker构建与推送 — 在推送到 master 分支或创建标签时，构建并发布多架构（amd64/arm64）的Docker镜像到Docker Hub。

🔧 技术细节

安全机制

• 与巴西银行API的通信通过 mTLS（客户端数字证书）进行。
• OAuth2认证令牌 仅存储在内存中，并自动更新。
• 敏感文件（.env、证书、密钥）已包含在 .gitignore 中。

📄 许可证

本项目采用 ISC许可证。