mcp-itau

@codespar/mcp-itau

适用于 Itaú Unibanco 的 MCP 服务——巴西最大的私营银行。

Itaú 在该国拥有规模最大的私营银行 API。处理大量 Pix、boleto 和现金管理业务的商户会直接接入，而不是通过 PSP。

状态：alpha（0.1.0-alpha.1）

Itaú 的开发者门户受合同限制——只有完成入驻的商户才能查看 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 bearer 令牌，或返回缓存的令牌。
send_pix	从商户的 Itaú 账户发起 Pix 付款。
create_pix_qr	创建带二维码的动态 Pix 收款（cob）。
get_pix	根据 BCB 的 endToEndId（E）查询 Pix 交易。
resolve_dict_key	解析 DICT 密钥（CPF、CNPJ、email、phone、EVP），在发送 Pix 前获取账户所有者的数据。
refund_pix	退还先前收到的 Pix（devolução）。
create_boleto	通过 Itaú Cobrança 开具 boleto。
get_boleto	根据 Itaú 标识符（id 或 nosso_numero）查询 boleto。
cancel_boleto	在付款前取消（baixa）未结清的 boleto。
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、email、phone 或 EVP）。
delete_pix_key	删除商户拥有的 DICT 密钥。
list_pix_keys	列出商户 Itaú 账户当前登记的 DICT 密钥。
get_boleto_pdf	下载已开具 boleto 的 PDF。
send_ted	向其他银行的账户发送 TED 转账。
transfer_between_accounts	TAA——在两个 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)

身份验证

每次调用都必须同时具备以下两项：

1. OAuth2 client_credentials——服务会调用令牌端点，将 bearer 令牌缓存至到期前约 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 规范进行验证，并提交 PR。
• 沙盒主机名是猜测的。 Itaú 会为每家商户提供一个沙盒子域名；如果分配给你的沙盒 URL 不同，请编辑 BASE_URL 进行覆盖。
• Arrecadação 条码验证在此 alpha 版本中由服务端执行，目前尚无客户端 mod-10 / mod-11 校验。

企业版

需要为 Agent 支付配置治理、预算限额和审计跟踪？CodeSpar Enterprise 在这些 MCP 服务之上提供策略引擎、支付路由和合规模板。

许可证

MIT