monapay-mcp

monapay-mcp

一个 MCP 服务，可让 Claude Code、Cursor 和 Codex 等 AI 编码 Agent（或任何 MCP 客户端）在编码时使用 MONA Pay：关联银行账户、创建结账链接和 VietQR 码、查询收款转账、配置和测试 webhook、发送电子邮件和 Zalo 群组通知，以及验证 webhook 签名。

已发布到 npm，包名为 monapay-mcp；同时已发布到 MCP Registry，名称为 vn.monapay/monapay-mcp。

安装

需要 Node.js 18 或更高版本，以及 MONA Pay API 密钥（客户端 ID 和客户端密钥，可在 MONA Pay 控制面板中创建）。

npx -y monapay-mcp   # starts the server over stdio

Claude Code

claude mcp add monapay \
  -e MONAPAY_CLIENT_ID=your_client_id \
  -e MONAPAY_CLIENT_SECRET=your_client_secret \
  -- npx -y monapay-mcp

Cursor（.cursor/mcp.json）和 Claude Desktop（claude_desktop_config.json）

{
  "mcpServers": {
    "monapay": {
      "command": "npx",
      "args": ["-y", "monapay-mcp"],
      "env": { "MONAPAY_CLIENT_ID": "client_id", "MONAPAY_CLIENT_SECRET": "client_secret" }
    }
  }
}

Codex（~/.codex/config.toml）

[mcp_servers.monapay]
command = "npx"
args = ["-y", "monapay-mcp"]
env = { MONAPAY_CLIENT_ID = "client_id", MONAPAY_CLIENT_SECRET = "client_secret" }

配置

变量	必需	含义
MONAPAY_CLIENT_ID	是（推荐）	在控制面板中创建的 API 密钥的 client_id
MONAPAY_CLIENT_SECRET	是（推荐）	client_secret，仅显示一次；用于获取 OAuth 令牌并授权写入操作
MONAPAY_USERNAME	旧版	MONA Pay 用户名，仅在未设置客户端凭据时使用
MONAPAY_PASSWORD	旧版	密码；对于启用了 2FA 的账户，此方式不可用
MONAPAY_BASE_URL	否	默认为 https://api.monapay.vn

建议使用客户端凭据，而不是用户名和密码，因为启用了 2FA 的账户无法使用密码登录。

用法

工具

工具	功能
monapay_quickstart	入口：检查账户状态（是否已关联银行账户/虚拟账户、是否已配置 webhook），并返回后续步骤
monapay_whoami	验证连接并返回账户名称和套餐
monapay_me	已登录账户的个人资料
monapay_link_bank_start · monapay_link_bank_verify_otp	关联 ACB 账户并创建虚拟账户（首次 OTP）
monapay_notification_register · monapay_notification_verify_otp	开启入账通知（第二次 OTP）
monapay_list_bank_accounts · monapay_list_virtual_accounts	已关联的银行账户及其虚拟账户（VA）
monapay_get_payment_profile · monapay_set_payment_profile	查看或设置托管结账页面使用的资料
monapay_create_checkout · monapay_get_checkout · monapay_list_checkouts · monapay_cancel_checkout	创建、查看、筛选和取消托管结账会话
monapay_create_qr · monapay_cancel_qr	为订单创建或取消动态 VietQR
monapay_list_transactions	某个 VA 的入账交易（每页最多 100 条），用于对账
monapay_get_transaction	在某个 VA 中通过 transaction_code 或 ID 查找一笔入账交易
monapay_get_transactions_summary	指定日期范围内的入账总额、交易数量和每日数据
monapay_sandbox_transaction	创建一笔模拟入账交易；webhook、Telegram、电子邮件和 Zalo 通知的触发方式与真实交易相同。如果没有 VA，则会发放一个沙盒 VA
monapay_list_webhooks · monapay_create_webhook · monapay_update_webhook · monapay_delete_webhook	Webhook 配置（NONE、API_KEY 或 HMAC_SHA256；推荐使用 HMAC）
monapay_test_webhook · monapay_webhook_logs · monapay_webhook_stats	发送虚拟 webhook、查看逐次投递记录、成功率 / P95
monapay_list_email_configs · monapay_create_email_config · monapay_update_email_config · monapay_delete_email_config	电子邮件通知配置，支持 1 到 10 位收件人
monapay_verify_email · monapay_resend_email_verification · monapay_test_email	使用 6 位代码验证收件人、重新发送代码、发送测试电子邮件
monapay_email_logs · monapay_email_stats	投递元数据、成功率 / P95 和错误分组
monapay_list_email_suppressions · monapay_remove_email_suppression	查看和移除被抑制的地址
monapay_list_zalo_groups · monapay_create_zalo_group · monapay_update_zalo_group · monapay_delete_zalo_group	Zalo 群组通知配置
monapay_test_zalo_group · monapay_zalo_group_logs	发送测试消息并查看 Zalo 群组投递记录
monapay_retry_transaction	重新发送某笔交易的 webhook 或 Telegram 通知
monapay_generate_key	生成新的 client_secret
monapay_rotate_key	当前密钥可能泄露时轮换其密钥
monapay_verify_signature	在本地验证 webhook 签名，不发起网络请求
monapay_generate_webhook_snippet	为 PHP、Node 或 Python 生成 webhook 接收代码，并附带示例负载

资源和提示词

• monapay://docs/llms：MONA Pay 文档的机器可读索引。
• monapay://docs/{slug}：以 Markdown 格式提供的单个文档页面，例如 monapay://docs/webhooks/tich-hop-webhook。
• 提示词 integrate-monapay（参数 language、framework）：供 Agent 将 MONA Pay 集成到当前项目中的 6 步计划。

示例

“将银行转账自动确认功能集成到这个 Laravel 网站中，并使用 MONA Pay。”

Agent 调用 monapay_whoami，使用 monapay_generate_webhook_snippet(language="php") 获取收款方代码，将端点写入项目，通过 monapay_create_webhook(auth_type="HMAC_SHA256", secret_key=...) 注册端点，调用 monapay_test_webhook 触发测试，读取 monapay_webhook_logs 确认端点返回 200，然后使用 monapay_create_checkout 为每笔订单创建结账，并等待 CHECKOUT_PAID。

使用 OTP 关联银行账户

ACB 会将每个 OTP 发送到账户持有人登记的手机号。在步骤 2 和步骤 4，Agent 必须询问用户，绝不能猜测 OTP。

1. 使用 ACB 账号、手机号、客户类型、VA 前缀和标识符调用 monapay_link_bank_start。该工具会返回 acb_request_id，ACB 随后会发送第一个 OTP。
2. 向用户索取 OTP，然后调用 monapay_link_bank_verify_otp。该工具会返回 virtual_account_id 和 VA 号码。
3. 使用 virtual_account_id 调用 monapay_notification_register。ACB 随后会发送第二个 OTP。
4. 向用户索取第二个 OTP，然后调用 monapay_notification_verify_otp。现在，收到的转账会转发到你配置的 Webhook。

如果 OTP 错误或已过期，请重新调用上一步以获取新验证码。

Zalo 群组通知

群组必须包含 MONA 机器人（Gấu Mona），由 MONA 团队添加。group_id 为 10 至 25 位数字，可从 MONA Account/PMS 获取。

使用 group_id、易于识别的名称以及要接收的事件调用 monapay_create_zalo_group：TRANSACTION_IN、CHECKOUT_PAID、WEBHOOK_FAILED、VA_CREATED。你可以将其限制为一个 virtual_account_id，使用 monapay_test_zalo_group 发送测试通知，并通过 monapay_zalo_group_logs 检查送达情况。

Zalo 不会渲染 Markdown，因此 message_template 必须是纯文本。它支持 {amount}、{description}、{virtual_account_number}、{transaction_code} 和 {transfer_date}；也支持 {{amount}} 格式。

密钥轮换

monapay_rotate_key 使用当前密钥轮换与 MONAPAY_CLIENT_ID 匹配的密钥。旧密钥会立即失效；请在 MCP 配置中更新 MONAPAY_CLIENT_SECRET，并重启客户端。

Webhook 签名

X-Mona-Signature: sha256=<hex>，其中 hex = HMAC-SHA256(secret, "<X-Mona-Timestamp>.<raw_body>")。拒绝时间戳偏差超过 300 秒的请求，并使用恒定时间比较。重试期间 transaction_code 保持不变，因此请将其用作去重键。

开发

npm install
npm test     # build + node --test

# Calls a few read-only tools against a real account
MONAPAY_CLIENT_ID=... MONAPAY_CLIENT_SECRET=... MONAPAY_BASE_URL=https://api.monapay.vn npm run smoke

Agent 指南：https://monapay.vn/ai-agent · 文档：https://monapay.vn/docs

许可证

MIT

MONA Pay 是 The MONA Group 旗下 MONA Cloud 的一部分。