MCP Banco Inter

🚀 🏦 MCP Banco Inter

このサーバーは、MCP (Model Context Protocol) を使用して、Banco Inter Empresas (PJ) のAPIと統合するためのものです。 AIアシスタント（Claude、ChatGPT、Geminiなど）が自然言語で口座残高、取引履歴の照会、請求書の発行と管理を行うことができます。

✨ 主な機能

銀行取引

• 💰 普通預金口座の残高照会
• 📊 期間指定による取引履歴照会
• 📄 PDF形式の取引履歴ダウンロード

請求書（ボレート）

• 📋 フィルター（状況、期間）を指定して発行済みの請求書を一覧表示
• 🆕 新しい請求書を発行
• ❌ 請求書をキャンセル
• 📊 期間ごとの請求書の概要表示
• 📥 請求書のPDFをダウンロード

📋 事前要件

• Node.js 18以上 または Docker
• Banco InterのAPI資格情報（Portal do Desenvolvedor Inter で取得）:
  • CLIENT_ID と CLIENT_SECRET
  • デジタル証明書 (.crt) と秘密鍵 (.key)
  • 普通預金口座番号

⚙️ 設定

1. Banco Interの開発者ポータル で資格情報を取得します。

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 に含まれています。

🚀 インストールと使用方法

このサーバーは2つのトランスポートモードをサポートしています。

1️⃣ npx を使用した stdio モード（ローカルクライアントに推奨）

デフォルトのモードです。MCPクライアントがプロセスを起動し、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

💡 実際には、手動で実行することはありません。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

サーバーは以下のURLで利用可能です。

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   # Banco InterのAPI用のHTTPクライアント
└── types.ts          # リクエスト/レスポンスのTypeScriptインターフェース

🧪 テスト

# 単体テスト
npm run test:unit

# 統合テスト（.envが設定されている必要があります）
npm run test:integration

# すべてのテスト
npm test

📦 CI/CD

このプロジェクトは GitHub Actions を使用した自動化パイプラインを備えています。

• NPM Publish — v* タグを作成すると、自動的にNPMに公開されます。
• Docker Build & Push — master ブランチにプッシュするか、タグを作成すると、マルチアーキテクチャ（amd64/arm64）のDockerイメージがビルドされ、Docker Hubに公開されます。

🔒 セキュリティ

• Banco InterのAPIとの通信は mTLS（クライアントのデジタル証明書）を介して行われます。
• OAuth2認証トークンは メモリ内にのみ保存 され、自動的に更新されます。
• 機密ファイル（.env、証明書、キー）は .gitignore に含まれています。