mcp-matera

@codespar/mcp-matera

已弃用：没有可用的实时端点。 2026-09-27 使用两个公共 DNS 解析器（8.8.8.8 和 1.1.1.1）进行测量后发现：此服务调用的主机 api.matera.com 无法通过 DNS 解析。此服务中的任何工具都无法连接到服务。该包已在 npm 上弃用，仅保留在此代码库中供参考。如果你有可用的端点，请通过 MATERA_BASE_URL 将服务指向该端点。若要恢复此包，请在 mcp-dev-latam 中提交问题，并附上提供商记录的基础 URL。

面向 Matera 的 MCP 服务——巴西核心银行基础设施（BaaS），为基于 Pix、DICT 和 Pix Automático 构建业务的金融科技公司提供服务

为什么选择 Matera

Matera 是核心银行基础设施，而不是 PSP。根据供应商的案例研究，它处理巴西 Pix 交易的比例约为 10%。它的客户是基于 Pix 构建业务的金融科技公司——开设账户、通过 DICT 转账、注册 Pix Automático 协议——而不是接受 Pix 付款的商户（这类商户适用 Zoop / Asaas / Mercado Pago）。

这为 CodeSpar 目录开辟了一个有别于 PSP 服务的新领域：基于 Pix 构建业务的金融科技公司。Matera 归属于 banking，与 Stark Bank 和 Open Finance 并列，而不属于 payments。

在 Agent 需要以下操作时使用 Matera：

• 针对该金融科技公司自行开设的账户发起 Pix 收款
• 转账前查询 DICT，以解析 Pix 密钥
• 注册定期 Pix Automático 协议（BCB 于 2025 年推出的产品，目前只有少数提供商已上线）
• 通过该金融科技公司自己的 Matera 通道进行银行间转账

快速开始

Claude Desktop

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

{
  "mcpServers": {
    "matera": {
      "command": "npx",
      "args": ["-y", "@codespar/mcp-matera"],
      "env": {
        "MATERA_CLIENT_ID": "your-client-id",
        "MATERA_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Claude Code

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

Cursor / VS Code

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

{
  "servers": {
    "matera": {
      "command": "npx",
      "args": ["-y", "@codespar/mcp-matera"],
      "env": {
        "MATERA_CLIENT_ID": "your-client-id",
        "MATERA_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

工具（22）

工具	用途
create_pix_charge_static	创建静态 Pix 付款请求（与商户 Pix 密钥关联的可重复使用二维码）。
create_pix_charge_dynamic	创建动态 Pix 付款请求（带有效期的一次性二维码）。
get_pix_charge	按 txid 获取 Pix 付款请求（静态或动态）。
list_pix_charges	列出即时 Pix 付款请求（BCB /cob），支持按日期和状态筛选。
update_pix_charge	更新即时 Pix 付款请求（BCB PATCH /cob/{txid}）。
create_pix_charge_due	创建到期日 Pix 付款请求（BCB /cobv — 到期 Pix）。
get_pix_charge_due	获取到期日 Pix 付款请求（BCB GET /cobv/{txid}）。
create_pix_payment	发起一笔 Pix 转账（付款指令）。
get_pix_payment	按 endToEndId 获取一笔 Pix 付款。
refund_pix_payment	退还一笔 Pix 付款。
list_pix_payments	列出 Pix 转出付款，支持可选筛选条件。
list_pix_received	列出指定日期范围内记入商户账户的 Pix 转入款项。
resolve_pix_key	解析 Pix DICT 密钥，获取账户持有人身份及 ISPB／分行／账户信息。
list_dict_keys	列出在 Matera 商户账户注册的 DICT 密钥。
register_dict_key	为 Matera 商户账户注册（认领）一个 DICT 密钥。
delete_dict_key	删除商户持有的 DICT 密钥。
create_pix_automatico	注册 Pix Automático 定期扣款（BCB 2025 年定期 Pix 产品，/rec）。
get_pix_automatico	按 idRec 获取 Pix Automático 定期扣款。
cancel_pix_automatico	取消一项有效的 Pix Automático 定期扣款。
get_account_balance	获取由 Matera 管理的账户当前余额。
get_account_statement	获取由 Matera 管理的账户在指定日期范围内的对账单。
internal_transfer	记账处理两个均在 Matera 持有的账户之间的转账（TED-内部转账／内部转账）。

身份验证

Matera 的公开文档索引指出，服务端集成使用 secret-key 和 data-signature 标头，而 OAuth2 仅适用于移动端／Web UI 集成（doc-api.matera.com）。目前的 v0.1-alpha 脚手架实现的是通过 POST /auth/token 使用 OAuth2 客户端凭据的方式。这种配置几乎肯定不适用于服务端到服务端的场景；待我们能够通过在线沙盒验证后，将改为使用签名请求方案——详见下文“状态”部分。

环境变量

变量	必需	描述
MATERA_CLIENT_ID	是	Matera 签发的 OAuth2 client_id
MATERA_CLIENT_SECRET	是	OAuth2 client_secret（机密）
MATERA_BASE_URL	否	API 基础 URL。默认为 https://api.matera.com。沙盒 URL 因产品线而异，请咨询你的 Matera 联系人。

状态

v0.1.0-alpha.1 — 工具接口稳定，但线路路径尚未验证。

2026-04-24，我们尝试对照 doc-api.matera.com 验证每个端点路径。该文档站点可通过浏览器访问，但无法从我们的自动化环境获取（受 DNS / 网络限制；未发现登录墙）。公开搜索摘要和第三方参考资料确认了产品范围（Pix 收款、Pix 付款、DICT、Pix Automático）和身份验证模型（服务端 = secret-key + data-signature；OAuth2 = 仅限最终用户），但没有显示确切的 URL 路径。

在我们能够针对 Matera 沙盒运行该服务之前，以下内容仍然是假定值，未经验证：

领域	代码中的值	可疑原因
令牌端点	POST /auth/token（Basic 身份验证，grant_type=client_credentials）	可能不适用于服务端集成 — 请参阅身份验证
Pix 收款	/pix/charges/static、/pix/charges/dynamic、/pix/charges/{txid}	Matera 可能采用 BCB 的 /cob（即时）/ /cobv（指定日期）命名方式
Pix 付款	/pix/payments、/pix/payments/{e2eid}、/pix/payments/{e2eid}/refund	BCB 规范将退款路径命名为 /pix/{e2eid}/devolucao/{id}
DICT 查询	GET /pix/dict/{key}、GET /pix/dict/keys	BCB DICT 受 RSFN 限制；Matera 提供自己的封装。确切路径未知。
Pix Automático	POST /pix/automatico	几乎可以肯定只是占位符。BCB 2025 规范使用 POST /rec（定期支付）+ /cobr/{txid}（定期收款）。

上述 10 个工具的名称和输入架构是公开契约，并将保持稳定。只有 src/index.ts 中的内部 HTTP 调用会在我们通过沙盒验证后更改。如今将此服务用于 Matera 的正式租户，大多数调用都会返回 404。

请在仓库 Issue 中跟进验证工作；欢迎任何拥有 Matera 沙盒的人提交 PR。

路线图

v0.2（计划中）

• 为需要身份验证的端点提供签名请求身份验证路径（secret-key + data-signature）
• 开户（abertura de conta）— Matera IB 产品
• TED / 银行转账（非 Pix 渠道）
• Webhook 事件辅助工具

v0.3（计划中）

• Internet Banking Server 工具（对账单、余额、卡片管理）
• Boleto 签发
• Pix MED（特殊退款机制）流程

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

链接

• Matera
• Matera API 文档
• MCP Dev LATAM
• 落地页

企业版

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

许可证

MIT