zen

ZEN MCP

一个 MCP 服务，可让 AI 助手使用 ZEN.com Payment Gateway：托管支付链接、交易查询、退款、付款和报告。

项目页面

非官方。 本项目与 ZEN.com 无关联，也未获其认可或维护。

功能

只读工具：

• 列出终端支付方式和文档中记录的货币。
• 查询交易、支付链接和付款。
• 列出支付链接并请求对账报告。
• 在本地验证 IPN webhook 签名。

写入工具：

• 创建托管支付链接和二维码，无需处理银行卡数据。
• 捕获或取消交易，并发起全额或部分退款。
• 创建付款和客户记录。

免责声明

此集成基于公开的 ZEN 文档构建，开发时未使用真实商户账户。用于生产环境前，必须根据 ZEN 当前的 OpenAPI 或 Postman 集合核实端点版本、请求字段、响应字段、签名细节和 webhook 行为。项目包含模拟模式，可在没有账户的情况下进行评估。

安装

将已发布的软件包添加到 Claude Code：

claude mcp add zen --env ZEN_API_KEY=your_terminal_api_key -- npx -y @krystiangw/zen-mcp

对于 Claude Desktop，请将此条目添加到其 MCP 配置中：

{
  "mcpServers": {
    "zen": {
      "command": "npx",
      "args": ["-y", "@krystiangw/zen-mcp"],
      "env": {
        "ZEN_API_KEY": "your_terminal_api_key",
        "ZEN_PAYWALL_SECRET": "your_paywall_secret",
        "ZEN_IPN_SECRET": "your_ipn_secret",
        "ZEN_ENV": "sandbox"
      }
    }
  }
}

配置

变量	必需	描述
ZEN_API_KEY	模拟模式以外	终端 API Key，在 Authorization 中发送，不带 Bearer 前缀
ZEN_PAYWALL_SECRET	写入操作	用于对请求正文签名的 Checkout/paywall 密钥
ZEN_IPN_SECRET	webhook 验证	仅供 verify_webhook_signature 使用的 IPN 密钥
ZEN_ENV	否	sandbox（默认）或 production
ZEN_BASE_URL	否	API 基础 URL 覆盖值；优先级高于 ZEN_ENV
ZEN_MOCK	否	设置为 1 或 true 可启用确定性的离线响应
ZEN_HASH_ALG	否	sha224、sha256（默认）、sha384 或 sha512

在 ZEN 商户面板中，前往 my.zen.com → Shop settings → Terminal 查找 Terminal API Key。请先使用沙盒；默认 API 主机为 api.zen-test.com，但应向 ZEN 确认沙盒是否可用以及相关开户要求。

还没有商户账户？你可以开设 ZEN 商业账户。这是一个推荐链接：如果你通过此链接注册，本项目作者会获得推荐奖励，而你无需支付任何费用。本 README 中的其他链接均为普通链接。

工具

名称	类型	描述
list_payment_methods	读取	列出终端的支付方式
get_transaction	读取	按 ZEN ID 或商户 ID 获取交易
list_payment_links	读取	列出托管支付链接
get_payment_link	读取	获取一个托管支付链接
get_payout	读取	按 ZEN ID 获取付款
download_report	读取	请求下载报告
list_supported_currencies	读取	列出文档中记录的受支持货币
verify_webhook_signature	读取	在本地验证 ZEN IPN 签名
create_payment_link	写入	创建托管结账链接和二维码
refund_transaction	写入，有破坏性	发起全额或部分退款
capture_transaction	写入，有破坏性	捕获已授权的交易
cancel_transaction	写入，有破坏性	取消交易
create_payout	写入，有破坏性	发起一笔转出付款
create_customer	写入	创建客户记录

安全性

• 工具默认只读；涉及转账或退款的操作会标记为破坏性操作，供 MCP 客户端识别。
• 密钥只从环境变量读取，绝不会作为工具参数传入。
• 收款使用 ZEN 托管的链接，因此此服务不会收集或传输卡号。
• 签名算法遵循 ZEN 的公开文档，但文档未完整说明嵌套对象和数组的扁平化方式。请通过线上 API 验证。
• 信任任何 IPN Webhook 的内容前，都要使用 ZEN_IPN_SECRET 验证其签名。
• 使用遵循最小权限原则的终端凭据，并为写入工具启用人工确认。

无需账户即可演示

使用确定性的预设 API 响应运行服务：

ZEN_MOCK=1 ZEN_IPN_SECRET=demo npx -y @krystiangw/zen-mcp

verify_webhook_signature 会执行实际的密码学运算，而不是调用 API，因此即使在模拟模式下也需要密钥。演示时可使用任意值。

从开发环境中的代码检出目录运行：

npm install
npm run build
ZEN_MOCK=1 ZEN_IPN_SECRET=demo npm run inspect

开发

需要 Node.js 18 或更高版本。

npm install
npm run typecheck
npm run build
npm test
ZEN_MOCK=1 ZEN_IPN_SECRET=demo npm run inspect

路线图

• 只有在经过审慎的 PCI / 安全设计后才支持原始银行卡扣款；MVP 不包含此功能。
• 验证令牌化流程后，再支持定期付款和一键付款。
• 如果 ZEN 发布受支持的 API，再支持面向消费者的 ZEN 功能，例如返现和个人卡。
• 在 stdio MVP 之后，再支持远程 Streamable HTTP 传输和 OAuth。

许可证

MIT