mcp-itau

@codespar/mcp-itau

ブラジル最大の民間銀行であるItaú Unibanco向けのMCP サーバーです。

Itaúは、国内最大の民間銀行API群を運用しています。Pix、boleto、資金管理の大規模な業務を行う加盟店は、PSPを経由せず、直接連携します。

ステータス：アルファ版（0.1.0-alpha.1）

ItaúのDeveloper Portalは契約が必要です。Pix、Cobrança、Arrecadação、Extratoの完全なOpenAPI仕様は、オンボーディング済みの加盟店のみが閲覧できます。このサーバーのエンドポイントパスは、（a）BACEN Pix v2の標準パス、（b）Itaúの公開マーケティングページ、（c）Santander／Bradesco／BBに共通する規約をもとにした推定です。未検証のパスにはすべて、ソース内でTODO(verify)のフラグが付いています。

0.1.xでは正確なバージョンに固定してください。オンボーディング済みの加盟店が検証でき次第、ポータルの仕様に合わせてパスを修正します。

ツール（22）

ツール	用途
get_oauth_token	Itaú Developer Portal用のOAuth2 client_credentialsベアラートークンを発行するか、キャッシュ済みのトークンを返します。
send_pix	加盟店のItaú口座からPixの送金を開始します。
create_pix_qr	QRコード付きの動的なPix請求（cob）を作成します。
get_pix	BCBのendToEndId（E）を使ってPix取引を取得します。
resolve_dict_key	Pix送信前に、DICTキー（CPF、CNPJ、メールアドレス、電話番号、EVP）を口座所有者のデータに解決します。
refund_pix	以前に受け取ったPixを返金（devolução）します。
create_boleto	Itaú Cobrança経由でboletoを発行します。
get_boleto	Itaúの識別子（idまたはnosso_numero）を使ってboletoを取得します。
cancel_boleto	支払い前に未払いのboletoを取り消し（baixa）します。
get_statement	指定期間の口座明細取引を取得します。
arrecadacao_pay	Itaú Arrecadação経由で公共料金、税金、または公共サービス料金の請求書を支払います。
create_pix_cobv	支払期限付きのPix請求（cobv）を作成します。支払人が期限以降にも支払える、boletoに似たPixに使用します。
list_pix_charges	加盟店が期間内に登録した即時Pix請求（cob）を一覧表示します。
register_pix_key	加盟店が所有するItaú口座にDICTキー（CPF、CNPJ、メールアドレス、電話番号、EVP）を登録します。
delete_pix_key	加盟店が所有するDICTキーを削除します。
list_pix_keys	加盟店のItaú口座に現在登録されているDICTキーを一覧表示します。
get_boleto_pdf	発行済みboletoのPDFをダウンロードします。
send_ted	他行の口座にTED送金を行います。
transfer_between_accounts	TAA — 2つのItaú口座間で送金します（加盟店または取引相手が所有する口座）。
get_tariffs	加盟店の有効な契約に適用される料金表（Pixの取引ごとの料金、boletoの登録料金など）を照会します。
list_dda_bills	DDA（Débito Direto Autorizado）登録のもとで、加盟店向けに登録された請求書を一覧表示します。
schedule_payment	将来の日付の支払い（Pix、boleto、arrecadação、またはTED）を予約します。

インストール

npm install @codespar/[email protected]

環境変数

ITAU_CLIENT_ID="..."       # OAuth client_id from Itaú's Developer Portal
ITAU_CLIENT_SECRET="..."   # OAuth client_secret
ITAU_CERT_PATH="/abs/path/to/client.crt"   # mTLS client certificate
ITAU_KEY_PATH="/abs/path/to/client.key"    # mTLS private key
ITAU_ENV="sandbox"                          # or "production" (default: sandbox)

認証

すべての呼び出しで、次の2要素が両方とも必要です。

1. OAuth2 client_credentials — サーバーがトークンエンドポイントを呼び出し、有効期限の約60秒前までベアラートークンをキャッシュし、下流への呼び出しにAuthorization: Bearer <token>を付加します。
2. mTLS — BACENはPix v2で相互TLSを義務付けており、Itaúはすべての製品群でこれを適用しています。サーバーは指定したパスからクライアント証明書と秘密鍵を読み込み、Nodeのhttps.Agentを構築して、すべてのリクエストをこれ経由で送信します。

加盟店契約の締結後、Itaú Developer Portalから証明書と鍵のバンドルを取得します。これらはOAuth認証情報とは別のものです。

実行

# stdio (default)
npx @codespar/mcp-itau

# HTTP transport
MCP_HTTP=true MCP_PORT=3000 npx @codespar/mcp-itau

注意事項

• パスは未検証です。 src/index.ts の TODO(verify) マーカーを参照してください。オンボーディング済みの加盟店は、ポータルで発行された OpenAPI 仕様に照らして検証し、プルリクエストを作成してください。
• サンドボックスのホスト名は推測です。 Itaú は加盟店ごとにサンドボックスのサブドメインを発行します。割り当てられたサンドボックス URL が異なる場合は、BASE_URL を編集して上書きしてください。
• Arrecadação バーコードの検証は、このアルファ版ではサーバー側で行われます。クライアント側の mod-10／mod-11 チェックはまだありません。

エンタープライズ

エージェントによる支払いにガバナンス、予算上限、監査証跡が必要ですか？ CodeSpar Enterprise は、これらの MCP サーバーにポリシーエンジン、支払いルーティング、コンプライアンステンプレートを追加します。

ライセンス

MIT