mcp-celcoin

@codespar/mcp-celcoin

面向 Celcoin 的 MCP 服务 — 为 Pix、boleto、转账和充值提供 BaaS 基础设施

快速开始

Claude Desktop

添加到 ~/.config/claude/claude_desktop_config.json：

{
  "mcpServers": {
    "celcoin": {
      "command": "npx",
      "args": ["-y", "@codespar/mcp-celcoin"],
      "env": {
        "CELCOIN_CLIENT_ID": "your-client-id",
        "CELCOIN_CLIENT_SECRET": "your-client-secret",
        "CELCOIN_SANDBOX": "true"
      }
    }
  }
}

Claude Code

claude mcp add celcoin -- npx @codespar/mcp-celcoin

Cursor / VS Code

添加到 .cursor/mcp.json 或 .vscode/mcp.json：

{
  "servers": {
    "celcoin": {
      "command": "npx",
      "args": ["-y", "@codespar/mcp-celcoin"],
      "env": {
        "CELCOIN_CLIENT_ID": "your-client-id",
        "CELCOIN_CLIENT_SECRET": "your-client-secret",
        "CELCOIN_SANDBOX": "true"
      }
    }
  }
}

工具（18 个）

工具	用途
create_pix_payment	通过 Celcoin 创建 Pix 付款
get_pix_payment	根据交易 ID 获取 Pix 付款详情
create_pix_cob	创建 Pix 即时收款（cob）——为付款方生成 QR 码 / copia-e-cola
get_pix_cob	根据 transactionId 或 txid 获取 Pix 即时收款
create_pix_cobv	创建 Pix 到期收款（cobv）——类似 boleto 的 Pix 收款，设有到期日
lookup_pix_dict	查询 Pix DICT 密钥——将 Pix 密钥解析为账户持有人和银行信息
create_pix_devolution	创建 Pix devolução（退款）——退还收到的 Pix 交易款项
cancel_boleto	通过账单签发产品，根据 ID 取消已签发的 boleto
read_barcode	付款前授权（查询）boleto / 特许经营商条码——返回 transactionId、amount、totalUpdated、dueDate
pay_bill	确认支付此前已授权的账单——将 read_barcode 的 transactionId 作为 transactionIdAuthorize 传入
get_statement	获取指定日期范围内的账户对账单（extrato）
list_topup_providers	列出可用于充值的电信充值服务商（operadoras）
create_boleto	通过账单签发产品签发 boleto
get_boleto	根据 ID 获取已签发 boleto 的详情
create_transfer	通过 Celcoin 创建银行转账（TED/DOC）
get_balance	获取 Celcoin 账户余额
list_banks	列出巴西可用的银行（ISPB 代码）
create_topup	通过 Celcoin 创建手机 / 服务充值（recarga）

身份验证

Celcoin 使用 OAuth2 客户端凭据。服务会自动管理令牌刷新。

沙箱 / 测试

Celcoin 提供沙箱 sandbox.openfinance.celcoin.dev。设置 CELCOIN_SANDBOX=true 即可使用。

如果未设置 CELCOIN_SANDBOX，服务会调用 Celcoin 生产环境 api.openfinance.celcoin.com.br（在 0.2.3 之前，默认地址是 api-sec.celcoin.com.br，该主机并不存在）。Celcoin 仅接受通过 mTLS 发出的生产环境调用，且需要 Celcoin 签发的证书，并且只能来自你事先向其登记的 IP（Celcoin 文档）。来自其他 IP 的令牌调用会返回 401 "O seu IP ou certificado digital nao foi reconhecido"。此服务不会提供客户端证书，因此在生产环境中，请将 CELCOIN_BASE_URL 指向持有证书并终止 mTLS 的代理；直接调用生产环境会返回该 401 错误。

获取凭据

1. 前往 Celcoin 文档
2. 创建开发者账户
3. 注册应用以获取 OAuth2 凭据
4. 设置环境变量

环境变量

变量	必填	说明
CELCOIN_CLIENT_ID	是	OAuth2 客户端 ID
CELCOIN_CLIENT_SECRET	是	OAuth2 客户端密钥
CELCOIN_SANDBOX	否	设置为 "true" 以启用沙箱模式
CELCOIN_BASE_URL	否	覆盖 API 主机。默认值：https://api.openfinance.celcoin.com.br（生产环境）、https://sandbox.openfinance.celcoin.dev（沙箱）

路线图

v0.2（计划中）

• get_pix_key — 获取 Pix 密钥详情（DICT 查询）
• create_bill_payment — 创建账单 / 公用事业缴费
• get_bill_payment — 获取账单付款详情
• create_scheduled_transfer — 创建定时转账
• list_providers — 列出可用的服务提供商

v0.3（计划中）

• batch_topups — 处理多笔手机充值
• detailed_reports — 生成详细交易报告

想要贡献？提交 PR 或申请工具。

链接

• Celcoin 网站
• Celcoin API 文档
• MCP Dev LATAM
• 落地页

企业版

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

许可证

MIT