Xendit Mcp

xendit-mcp

适用于 Xendit 支付 API 的 Model Context Protocol 服务。支持通过发票创建支付链接、付款／转账、余额和交易，覆盖印度尼西亚、菲律宾、泰国、越南和马来西亚。

安装

npm install -g xendit-mcp

或者使用 npx xendit-mcp 按需运行。

从 0.1.x 升级

0.2.0 引入了会造成不兼容的默认设置。 如果你使用的是 0.1.x，并且依赖开箱即用的发票创建或单步付款功能，那么这些工具现在默认处于禁用状态。

要恢复旧行为，请在 MCP 配置的 env 中设置以下内容：

XENDIT_ENABLE_INVOICE_MUTATIONS=true
XENDIT_ENABLE_DISBURSEMENTS=true
XENDIT_ENABLE_LEGACY_ONE_SHOT_DISBURSEMENT=true

如果启用转账，还必须设置四项安全门槛（XENDIT_MAX_DISBURSEMENT_AMOUNT、XENDIT_MAX_DAILY_AMOUNT、XENDIT_ALLOWED_ACCOUNTS、XENDIT_APPROVAL_CODE），否则服务将拒绝启动。

建议迁移到新的两步付款流程（使用审批码执行 prepare_disbursement → confirm_disbursement），而不是重新启用旧版单步功能。详情请参阅安全。

面向用户的模式

产品可分为 3 种模式：

• read-only：读取余额、发票和交易
• invoices：只读模式，另外支持 create_invoice 和 expire_invoice
• guarded-payouts：发票模式，另外支持 prepare_disbursement 和 confirm_disbursement

对于非技术用户，最简单的辅助工具是：

npx xendit-mcp doctor
npx xendit-mcp setup

• doctor 会显示当前模式、已启用的功能以及仍受阻止的功能。
• setup 会根据你所需的模式生成 Claude Code 或 Claude Desktop 配置片段。

配置

1. 在 Xendit Dashboard 注册。
2. 前往 Settings → API Keys 并生成密钥。
3. 开发时使用测试密钥（xnd_development_...），生产环境使用正式密钥。

变量	必需	描述
XENDIT_API_KEY	是	测试或正式 API 密钥
XENDIT_ENABLE_INVOICE_MUTATIONS	否	设置为 true 以启用 create_invoice、expire_invoice 和 create_payment_link 提示词。默认禁用，以确保更安全的只读行为。
XENDIT_ENABLE_DISBURSEMENTS	否	设置为 true 以启用转账工具（资金转移）。默认禁用。
XENDIT_ALLOW_LIVE	否	设置为 true 以允许使用正式／生产密钥（前缀为 xnd_production_、iluma_production_、sk_live_）。默认拒绝。
XENDIT_MAX_DISBURSEMENT_AMOUNT	否	单次资金转出调用的硬性上限。设置为 0 或留空以禁用。
XENDIT_MAX_DAILY_AMOUNT	否	滚动 24 小时内所有资金转出调用的上限。设置为 0 或留空以禁用。
XENDIT_ALLOWED_ACCOUNTS	否	逗号分隔的允许列表，格式为 CHANNEL_CODE:ACCOUNT_NUMBER，例如 ID_BCA:1234567890。
XENDIT_PREPARE_TTL_SECONDS	否	已准备的转账令牌的有效时长。默认值为 300，最大值为 86400。
XENDIT_APPROVAL_CODE	否	当 XENDIT_ENABLE_DISBURSEMENTS=true 时必填。confirm_disbursement 和旧版单步付款功能需要人工审批码。请勿将其放入不可信的提示词上下文。
XENDIT_ENABLE_LEGACY_ONE_SHOT_DISBURSEMENT	否	仅当你有意使用旧版 create_disbursement 单步工具时设置为 true。默认禁用。

引导式设置

如果不想手动编辑环境变量，请运行：

npx xendit-mcp setup

系统会询问你使用的客户端和所需模式，然后输出一段可直接粘贴的 Claude 配置片段，其中包含密钥占位符。

如果 MCP 已在 Claude 中连接，你也可以让 Claude 使用：

• get_workspace_mode
• guided_setup

如果可用，guided_setup 会在 Claude Code 中使用 MCP 引导式输入，因此用户看到的是表单，而不是原始配置详情。

Claude Desktop

编辑 claude_desktop_config.json：

{
  "mcpServers": {
    "xendit": {
      "command": "npx",
      "args": ["-y", "xendit-mcp"],
      "env": {
        "XENDIT_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Code

claude mcp add xendit --env XENDIT_API_KEY=your-api-key -- npx -y xendit-mcp

Cursor

按照与 Claude Desktop 相同的结构，添加到 ~/.cursor/mcp.json。

工具

工具	描述
get_workspace_mode	说明当前启用的 Xendit 模式、已启用的功能，以及解锁更多功能的最安全后续步骤。
guided_setup	为 read-only、invoices 或 guarded-payouts 生成 Claude Code 或 Claude Desktop 配置片段。
get_balance	按类型（CASH、HOLDING、TAX）查询账户余额。
list_invoices	按状态、日期范围或货币筛选并列出发票。
get_invoice	获取单张发票。
create_invoice	创建付款发票并返回付款链接。除非 XENDIT_ENABLE_INVOICE_MUTATIONS=true，否则禁用。
expire_invoice	将有效发票设为过期。除非 XENDIT_ENABLE_INVOICE_MUTATIONS=true，否则禁用。
list_transactions	列出收款、付款、退款、转账和余额调整。
prepare_disbursement	暂存一笔出款调用，并返回一个短时有效的确认令牌。除非 XENDIT_ENABLE_DISBURSEMENTS=true，否则禁用。
confirm_disbursement	执行先前准备的出款令牌。需要 approvalCode。除非 XENDIT_ENABLE_DISBURSEMENTS=true，否则禁用。
cancel_disbursement	取消已准备的出款令牌。除非 XENDIT_ENABLE_DISBURSEMENTS=true，否则禁用。
create_disbursement	旧版单步付款／出款。需要 approvalCode 和明确启用旧版功能。除非同时设置 XENDIT_ENABLE_DISBURSEMENTS=true 和 XENDIT_ENABLE_LEGACY_ONE_SHOT_DISBURSEMENT=true，否则禁用。
get_disbursement	查看付款／出款状态。除非 XENDIT_ENABLE_DISBURSEMENTS=true，否则禁用。
list_disbursement_banks	列出付款渠道，例如 ID_BCA 和 PH_BPI。除非 XENDIT_ENABLE_DISBURSEMENTS=true，否则禁用。

提示词

提示词	描述
check_balance	报告账户余额。
recent_payments	过去 N 天收到的付款。
create_payment_link	为客户生成付款链接。除非 XENDIT_ENABLE_INVOICE_MUTATIONS=true，否则禁用。
unpaid_invoices	列出待处理的发票。
daily_summary	今日付款活动。

资源

资源	URI	描述
支持的银行	xendit://banks	印度尼西亚和菲律宾常见的付款渠道别名。
设置指南	xendit://setup	当前模式、设置命令以及通俗易懂的模式说明。
API 信息	xendit://info	Xendit API 概览和文档链接。

示例查询

What's my current Xendit balance?
Saldo Xendit saya berapa?

With `XENDIT_ENABLE_INVOICE_MUTATIONS=true`:
Create an invoice for Rp 500,000 for "Website design deposit".
Buatkan invoice Rp 500.000 untuk "Deposit desain website".

Show me all unpaid invoices.
Tampilkan semua invoice yang belum dibayar.

设置 XENDIT_ENABLE_DISBURSEMENTS=true 后：

Prepare a Rp 1,000,000 payout to Ahmad at BCA, then wait for my confirmation.
Siapkan payout Rp 1.000.000 ke Ahmad di BCA, lalu tunggu konfirmasi saya.

List available payout channels in the Philippines.

环境

Xendit 会分别签发测试和正式 API 密钥。测试密钥会连接到 Xendit 沙盒，不会有真实资金流动。正式密钥（xnd_production_...、iluma_production_...、sk_live_...）则会连接到生产环境。

安全性

此服务可通过 Xendit API 转移真实资金。关键安全措施：

• 默认只读。 除非设置 XENDIT_ENABLE_INVOICE_MUTATIONS=true，否则会禁用发票写入工具。除非设置 XENDIT_ENABLE_DISBURSEMENTS=true，否则会禁用资金转移工具。
• 默认拒绝生产密钥。 除非设置 XENDIT_ALLOW_LIVE=true，否则启动时会拒绝前缀为 xnd_production_、iluma_production_ 或 sk_live_ 的密钥。请务必先使用开发密钥（xnd_development_...）进行测试。
• 资金转移默认失败关闭。 如果启用付款，除非已配置 XENDIT_MAX_DISBURSEMENT_AMOUNT、XENDIT_MAX_DAILY_AMOUNT、XENDIT_ALLOWED_ACCOUNTS 和 XENDIT_APPROVAL_CODE，否则服务会拒绝启动。
• 人工参与流程。 confirm_disbursement 同时要求提供暂存令牌和单独的 approvalCode。
• 默认关闭旧版单步付款。 只有设置 XENDIT_ENABLE_LEGACY_ONE_SHOT_DISBURSEMENT=true 后，才会注册 create_disbursement。
• 硬性上限和允许列表。 XENDIT_MAX_DISBURSEMENT_AMOUNT、XENDIT_MAX_DAILY_AMOUNT 和 XENDIT_ALLOWED_ACCOUNTS 可在付款发出前确保失败关闭。
• 幂等性。 付款调用会将你的 externalId 用作 Idempotency-Key，因此安全重试不会创建重复转账。
• 始终提供设置辅助工具。 即使在只读模式下，也会公开 get_workspace_mode 和 guided_setup，以便用户了解哪些操作受限，以及如何安全地启用下一种模式。
• 重要限制。 如果向不可信的模型上下文暴露敏感的读取或写入工具，则没有任何 MCP 服务能完全免受提示词注入的影响。这些默认设置可以降低风险，但你仍应只将此服务连接到可信的 Agent 工作流。

即使启用了这些防护，在批准工具调用前，也请审核任何资金转移请求。将源自模型输出的工具输入视为不可信内容。

付款生命周期

已确认的付款不一定会立即成功或失败。Xendit 会返回以下状态之一，终态可能要在几秒或几分钟后才会到达：

• ACCEPTED — 已被 Xendit 接受，渠道正在处理中
• REQUESTED — 已提交到目标渠道，正在等待渠道响应
• SUCCEEDED — 资金已送达
• FAILED — 最终失败（例如 INVALID_DESTINATION、REJECTED_BY_CHANNEL、INSUFFICIENT_BALANCE）

某些目标（在 PHP 沙盒测试中观察到）会在 REQUESTED 状态停留一段时间，之后才转为 FAILED。在认定状态已最终确定前，请务必使用 get_disbursement 重新获取状态。不要将 confirm_disbursement 的初始响应视为资金已送达的证明。

沙盒验证范围

0.2.0 已于 2026 年 5 月 25 日使用 IDR 和 PHP 开发密钥，在 Xendit 沙盒中完成验证。已验证的流程：

• 创建／获取／列出／过期发票（IDR + PHP）
• 发现付款渠道（PHP）
• 受保护的付款 prepare → confirm → get（IDR + PHP）
• 付款失败原因 INVALID_DESTINATION 和 REJECTED_BY_CHANNEL（仅 PHP——IDR 沙盒密钥的 balance: 0，因此 IDR 的失败案例显示为 INSUFFICIENT_BALANCE，而非特定于目标的失败）

泰国、越南和马来西亚的行为尚未使用真实沙盒密钥进行验证。其行为可能相似，但不能声称已测试。

可选的 Claude Code 加固措施

Claude Code 支持 PreToolUse hooks，可为 confirm_disbursement 等敏感工具强制显示额外的审批对话框。这样一来，你就能在模型上下文之外增加第二道控制措施。

.claude/settings.json 示例片段：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__xendit__confirm_disbursement",
        "hooks": [
          {
            "type": "command",
            "command": "printf '%s' '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"ask\",\"permissionDecisionReason\":\"Human review required before confirm_disbursement.\"}}'"
          }
        ]
      }
    ]
  }
}

免责声明

这是一个非官方的社区构建 MCP 服务。与 Xendit 无关联，也未获其认可或赞助。Xendit 是其各自所有者的商标。使用风险由你自行承担。对于因误用、提示词注入或漏洞而导致的资金损失，作者概不负责。

许可证

MIT