mcp-sicoob

Name: mcp-sicoob
Author: codespar

本地服务

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

代码仓库

关于 mcp-sicoob

mcp-sicoob 是面向巴西 Sicoob 合作银行网络的 MCP 服务，覆盖 Pix（cob/cobv/DICT）、Cobrança boleto 及 SPB 接口。项目目前为 alpha 版本，接口路径尚待官方文档核验。服务同时要求 OAuth2 client_credentials 与 mTLS 双重认证。

主要功能

01Pix 即时收费（cob）与到期收费（cobv）工具
02DICT 键查询、注册与删除
03Boleto 开具、查询与撤销
04SPB 账户余额查询
05OAuth2 令牌缓存与 mTLS 客户端证书加载

适用场景

01为商户生成 Pix 收款二维码并查询收款状态
02在发送 Pix 前核验 DICT 键对应的账户信息
03通过 MCP 客户端开具并撤销 boleto

MCP 相关

该项目是 MCP 服务，向 MCP 客户端暴露 13 个工具，用于调用 Sicoob 开发者门户的 Pix、Cobrança 与 SPB 接口。

配置

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

mcp.json · 通用配置

{
  "mcpServers": {
    "codespar-mcp-sicoob": {
      "command": "npx",
      "args": [
        "-y",
        "@codespar/mcp-sicoob"
      ],
      "env": {
        "SICOOB_CLIENT_ID": "<SICOOB_CLIENT_ID>",
        "SICOOB_CLIENT_SECRET": "<SICOOB_CLIENT_SECRET>",
        "SICOOB_CERT_PATH": "<SICOOB_CERT_PATH>",
        "SICOOB_KEY_PATH": "<SICOOB_KEY_PATH>",
        "SICOOB_ENV": "<SICOOB_ENV>"
      }
    }
  }
}

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

需要配置的环境变量

SICOOB_CLIENT_IDSicoob OAuth client_id issued via the Developers Portal after cooperative onboarding.

SICOOB_CLIENT_SECRET密钥Sicoob OAuth client_secret.

SICOOB_CERT_PATHAbsolute path to the mTLS client certificate (.crt or .pem). BACEN mandates mTLS for Pix v2.

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

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

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

安装包

npm@codespar/mcp-sicoob0.1.0-alpha.4stdio

工具

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

此工具无需参数。

详细介绍

@codespar/mcp-sicoob

适用于 Sicoob 的 MCP 服务——巴西最大的合作银行网络。

Sicoob 的 Pix 交易量长期位居巴西支付服务提供商（PSP）前四。巴西信贷合作社系统（Sistema de Cooperativas de Crédito do Brasil）将数百家地区合作社整合在一起，并通过统一的开发者门户提供 Pix、Cobrança（银行缴费单）和 SPB API。

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

Sicoob 开发者门户需要先完成合作社入驻才能访问。本服务中的端点路径是根据以下信息推测得出的：(a) BACEN Pix v2 标准路径，(b) Sicoob 公开文档片段，以及 (c) Itaú / Bradesco / BB 通用的约定。所有未经验证的路径都在源代码中标注了 TODO(verify)。

在 0.1.x 期间，请固定使用精确版本；待已入驻的合作社成员能够验证后，我们会修正路径，使其符合门户规范。

工具（13）

工具	用途
`get_oauth_token`	为 Sicoob 开发者门户生成 OAuth2 client_credentials 持有者令牌，或返回缓存的令牌。
`create_pix_cob`	创建带有二维码的即时 Pix 收款单（cob）。
`get_pix_cob`	根据 txid 获取即时 Pix 收款单。
`list_pix_cob`	列出商户在指定日期范围内登记的即时 Pix 收款单（cob）。
`create_pix_cobv`	创建有到期日的 Pix 收款单（cobv）——类似银行缴费单的 Pix，可在到期日或之后支付，并支持可选的 fin...
`get_pix_cobv`	根据 txid 获取有到期日的 Pix 收款单（cobv）。
`lookup_dict_key`	将 DICT 密钥（CPF、CNPJ、邮箱、电话、EVP）解析为所有者账户数据，以便发送 Pix。
`register_dict_key`	在合作社成员持有的 Sicoob 账户上登记 DICT 密钥（CPF、CNPJ、邮箱、电话或 EVP）。
`delete_dict_key`	删除合作社成员拥有的 DICT 密钥。
`create_boleto`	通过 Sicoob Cobrança 开具 boleto。
`get_boleto`	根据 Sicoob 标识符（id 或 nosso_numero）获取 boleto。
`cancel_boleto`	在 boleto 付款前取消（baixa）未结清的 boleto。
`get_account_balance`	通过 Sicoob SPB 查询商户合作社账户余额。

安装

npm install @codespar/[email protected]

环境变量

SICOOB_CLIENT_ID="..."       # OAuth client_id from Sicoob's Developers Portal
SICOOB_CLIENT_SECRET="..."   # OAuth client_secret
SICOOB_CERT_PATH="/abs/path/to/client.crt"   # mTLS client certificate
SICOOB_KEY_PATH="/abs/path/to/client.key"    # mTLS private key
SICOOB_ENV="sandbox"                          # or "production" (default: sandbox)

身份验证

每次调用都必须同时满足两个身份验证因素：

OAuth2 client_credentials——服务会调用令牌端点，将持有者令牌缓存至过期前约 60 秒，并在下游调用中附加 Authorization: Bearer <token>。
mTLS——BACEN 要求 Pix v2 使用双向 TLS，Sicoob 也在所有产品系列中强制使用 mTLS。服务会从你设置的路径加载客户端证书和私钥，构建 Node https.Agent，并通过该 Agent 路由每个请求。

证书和密钥包由 Sicoob 开发者门户在合作社完成入驻后颁发，与 OAuth 凭据相互独立。

运行

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

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

注意事项

路径尚未验证。 请查看 src/index.ts 中的 TODO(verify) 标记。已入驻的合作社应根据门户提供的 OpenAPI 规范进行验证，并提交 PR。
沙盒主机地址为推测值。 Sicoob 会为每家合作社分配一个沙盒子域名；如果你获得的沙盒 URL 不同，请修改 BASE_URL。