mcp-btg

Name: mcp-btg
Author: codespar

本地服务

github.com/codespar金融数据2754 周前更新

代码仓库

关于 mcp-btg

mcp-btg 是面向 BTG Pactual 的 MCP 服务，覆盖 Pix、Boleto、账户与投资产品（CDB、LCI、LCA、基金）。该项目目前为 alpha 版本，接口路径尚未经开发者门户规范验证。它面向已完成 BTG 合同接入的商户与金融科技团队，并使用 OAuth2 与 mTLS 双重认证。

主要功能

01Pix 即时收款与查询（cob）
02Boleto 开具与查询
03BTG+ 活期账户余额与对账单查询
04固定收益及投资持仓列表
05基金申购、赎回与可购基金查询
06OAuth2 client_credentials 与 mTLS 双重认证

适用场景

01商户通过 Agent 生成 Pix 收款码并核对到账
02金融科技团队查询账户余额与对账单
03Agent 查询 CDB、LCI、LCA 等固定收益持仓

MCP 相关

该项目是 MCP 服务，向 MCP 客户端暴露 12 个工具，用于 Pix、Boleto、账户与投资相关操作。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "codespar-mcp-btg": {
      "command": "npx",
      "args": [
        "-y",
        "@codespar/mcp-btg"
      ],
      "env": {
        "BTG_CLIENT_ID": "<BTG_CLIENT_ID>",
        "BTG_CLIENT_SECRET": "<BTG_CLIENT_SECRET>",
        "BTG_CERT_PATH": "<BTG_CERT_PATH>",
        "BTG_KEY_PATH": "<BTG_KEY_PATH>",
        "BTG_ENV": "<BTG_ENV>"
      }
    }
  }
}

启动命令npx -y @codespar/mcp-btg

需要配置的环境变量

BTG_CLIENT_IDBTG OAuth client_id issued via the Developer Portal after contract onboarding.

BTG_CLIENT_SECRET密钥BTG OAuth client_secret.

BTG_CERT_PATHAbsolute path to the mTLS client certificate (.crt or .pem). BACEN mandates mTLS for Pix v2; BTG enforces it across product families.

BTG_KEY_PATH密钥Absolute path to the mTLS private key (.key or .pem).

BTG_ENVEnvironment: 'sandbox' or 'production'. Defaults to 'sandbox'.

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@codespar/mcp-btg0.1.0-alpha.3stdio

工具

收录的工具列表 · 更新于 2 周前

此工具无需参数。

详细介绍

@codespar/mcp-btg

适用于 BTG Pactual 的 MCP 服务——巴西（以及拉美）最大的投资银行。

BTG 在机构经纪业务基础上运行数字银行与投资服务平台 BTG+。商户和金融科技公司接入 BTG，可同时使用 Pix／boleto 支付渠道，以及投资账户 API（CDB、LCI、LCA、债券、基金）；其他零售银行无法提供如此深入的服务。

状态：alpha（`0.1.0-alpha.1`）

BTG 的开发者门户受合同限制——只有已完成接入的合作方才能查看完整的 OpenAPI 规范。本服务中的端点路径均为最佳猜测，依据包括：（a）BACEN Pix v2 标准路径，（b）BTG 的公开营销页面，以及（c）巴西其他银行的通用惯例。所有未经验证的路径均已在源代码中标记为 TODO(verify)。

在 0.1.x 期间，请固定使用精确版本；待已完成接入的合作方验证后，将根据门户规范修正路径。

工具（12）

工具	用途
`get_oauth_token`	为 BTG 开发者门户生成 OAuth2 client_credentials bearer 令牌，或返回缓存的令牌。
`create_pix_cob`	创建即时 Pix 收款（cob），并生成 QR 码。
`get_pix_cob`	根据 txid 获取即时 Pix 收款（cob）。
`create_boleto`	通过 BTG Cobrança 开具 boleto。
`get_boleto`	根据 BTG 标识符（id 或 nosso_numero）获取 boleto。
`get_account_balance`	获取 BTG+ 活期账户（conta corrente）的可用余额。
`get_account_statement`	获取指定期间的账户交易明细。
`list_investment_positions`	列出合作方在 BTG 持有的投资头寸，范围涵盖固定收益资产类别（CDB、LCI、L...
`get_portfolio_summary`	汇总合作方在 BTG 持有的所有资产类别（固定收益、基金、股票、国债...）的投资组合。
`list_funds_available`	列出 BTG 平台上可供分销的基金。
`subscribe_to_fund`	在 BTG 分销平台上申购（aplicar）基金。
`redeem_from_fund`	赎回（resgatar）基金。

安装

npm install @codespar/[email protected]

环境

BTG_CLIENT_ID="..."       # OAuth client_id from BTG's Developer Portal
BTG_CLIENT_SECRET="..."   # OAuth client_secret
BTG_CERT_PATH="/abs/path/to/client.crt"   # mTLS client certificate
BTG_KEY_PATH="/abs/path/to/client.key"    # mTLS private key
BTG_ENV="sandbox"                          # or "production" (default: sandbox)

身份验证

每次调用都必须同时满足以下两个条件：

OAuth2 client_credentials——服务调用令牌端点，将 bearer 令牌缓存至过期前约 60 秒，并在下游调用中附加 Authorization: Bearer <token>。
mTLS——BACEN 要求 Pix v2 使用双向 TLS，BTG 也在所有产品类别（银行业务与投资）中强制执行该要求。服务从你设置的路径加载客户端证书和私钥，创建 Node https.Agent，并通过该 Agent 路由所有请求。

完成合同接入后，你可以从 BTG 开发者门户获取证书与密钥包。它们与 OAuth 凭据相互独立。

运行

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

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

注意事项

路径未经验证。 请查看 src/index.ts 中的 TODO(verify) 标记。已完成接入的合作方应对照门户提供的 OpenAPI 规范进行验证，并提交 PR。
沙盒主机名为猜测。 BTG 会为每个合作方提供独立的沙盒子域名；如果你获配的沙盒 URL 不同，请编辑 BASE_URL 进行覆盖。
**投资服务（CDB／LCI／LCA／债券／基金）**是本仓库中区别于零售银行 MCP 服务的特色；待 OpenAPI 规范经过逐字节验证后，字段结构可能会调整。