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許可證。