MyFatoorah MCP

MyFatoorah MCP

面向大模型的 Model Context Protocol 服务，适用于 MyFatoorah API。它让 Claude、VS Code、Cursor 和其他 MCP 宿主能够通过专用工具发现支付方式、创建支付链接、验证付款、查看发票和管理退款。

这是一个独立的社区项目，并非 MyFatoorah 官方产品。使用正式账户前，请先在沙盒中测试。

有关宿主配置、Inspector 测试、Agent 提示词、付款验证、退款和故障排除的分步指南，请参阅使用指南。

要求

• Node.js 20 或更高版本
• MyFatoorah API 令牌，其权限仅需满足所用工具的要求

设置

npm install
cp .env.example .env
npm run build

在 MCP 宿主的环境中设置 MYFATOORAH_API_TOKEN。服务不会自动加载 .env；VS Code 调试配置除外。

环境变量

变量	必需	默认值	说明
MYFATOORAH_API_TOKEN	是，调用 API 时必需	—	Bearer 令牌。切勿将其暴露给 Agent 提示词。
MYFATOORAH_ENVIRONMENT	否	test	test、kuwait、uae、saudi_arabia、qatar 或 egypt
MYFATOORAH_BASE_URL	否	环境 URL	用于受支持的 MyFatoorah 部署或测试代理的 HTTPS 覆盖地址
MYFATOORAH_TIMEOUT_MS	否	30000	请求超时时间，范围为 1 至 300000 ms

科威特也涵盖巴林、约旦和阿曼共用的 API 源站。多国家账户在每个国家使用单独的令牌。

连接 MCP 宿主

在宿主配置中使用绝对路径。请在本地替换 /absolute/path/to/myfatoorah-mcp 和令牌占位符。

Claude Desktop

将此服务添加到 Claude Desktop 的 MCP 配置中：

{
  "mcpServers": {
    "myfatoorah": {
      "command": "node",
      "args": ["/absolute/path/to/myfatoorah-mcp/dist/index.js"],
      "env": {
        "MYFATOORAH_API_TOKEN": "YOUR_TOKEN",
        "MYFATOORAH_ENVIRONMENT": "test"
      }
    }
  }
}

保存配置后，重启 Claude Desktop。

Claude Code

项目级配置可使用 .mcp.json（如果其中包含令牌，请勿提交到版本库）：

{
  "mcpServers": {
    "myfatoorah": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/myfatoorah-mcp/dist/index.js"],
      "env": {
        "MYFATOORAH_API_TOKEN": "YOUR_TOKEN",
        "MYFATOORAH_ENVIRONMENT": "test"
      }
    }
  }
}

VS Code / GitHub Copilot

随附的 .vscode/mcp.json 会启动构建好的服务，并安全地提示输入令牌。构建一次后，打开 MCP 服务视图，然后启动 myfatoorah。令牌不会存储在代码库中。

Cursor 和通用 stdio 宿主

使用与 Claude Desktop 示例相同的 command、args 和 env 值。MCP 协议消息通过 stdin/stdout 传递；服务诊断信息必须输出到 stderr。

发布到 npm 后，宿主也可以改用 npx -y myfatoorah-mcp 启动。

工具

工具	效果	用途
myfatoorah_get_payment_methods	只读	列出已启用的方法及其 ApiName 值
myfatoorah_create_payment	创建数据	使用 POST /v3/payments 创建托管结账或发票链接
myfatoorah_get_payment	只读	通过 PaymentId 获取权威付款详情
myfatoorah_get_invoice	只读	通过 InvoiceId 或外部标识符获取发票
myfatoorah_create_refund	有破坏性	创建全额或部分退款；需要 confirm: true
myfatoorah_get_refund	只读	通过 RefundId 获取退款详情
myfatoorah_api_request	不定	用于相对 /v2/ 或 /v3/ 路径的受限备用接口；执行变更需要确认

该服务还会公开：

• 资源 myfatoorah://configuration：环境、基础 URL、超时，以及是否已配置令牌——绝不包含令牌本身。
• 提示词 create-payment-safely：可重复使用的引导式付款链接工作流。

成功调用工具后，会返回简洁的文本摘要，以及包含 MyFatoorah 响应的机器可读 structuredContent。

安全付款工作流

1. 读取 myfatoorah://configuration，确认使用测试环境还是生产环境。
2. 如果要选择支付网关，请调用 myfatoorah_get_payment_methods 并使用其 ApiName。
3. 确认金额、币种、客户、通知方式和回调 URL。
4. 调用 myfatoorah_create_payment，并将其 PaymentURL 提供给客户。
5. 收到回调后，使用返回的 PaymentId 调用 myfatoorah_get_payment。重定向不能证明付款已完成；必须确认发票状态为 PAID，且交易状态为 SUCCESS。

生产环境中的退款会实际转移资金。在传入 confirm: true 之前，必须就确切的 PaymentId 和金额获得用户明确批准。

开发

npm run format
npm run lint
npm run typecheck
npm test
npm run build
npm run inspect

npm run inspect 会针对已编译的 stdio 服务启动官方 MCP Inspector。VS Code 还包含构建/测试任务和调试配置。

测试会模拟所有 MyFatoorah 请求；不会发起网络调用，也不需要令牌。

安全

• 使用权限最小化的 MyFatoorah API 密钥，并定期轮换。
• 将凭据放在宿主环境或密钥管理器中，绝不要放入源代码管理或模型上下文。
• 通用请求工具会拒绝绝对 URL、协议相对 URL、路径遍历，以及 /v2/ 和 /v3/ 之外的路径，以防凭据外泄。
• API 错误和 Bearer 值在传递给模型之前会被脱敏。
• 对支持的变更操作，优先使用幂等键和稳定的订单标识符。
• 不要将此 stdio 进程作为未经身份验证的网络服务公开。
• 本项目有意不将直接处理银行卡作为专用工具建模；这需要符合 PCI 标准。

API 范围与参考资料

专用工具使用截至 2026 年 8 月 MyFatoorah 文档中列出的 v3 路由：

• GET /v3/payment-methods
• POST /v3/payments
• GET /v3/payments/{paymentId}
• GET /v3/invoices/{invoiceId}
• GET /v3/invoices/externalIdentifier/{externalIdentifier}
• POST /v3/refunds
• GET /v3/refunds/{refundId}

参考资料：

• MyFatoorah API 密钥和区域 URL
• MCP TypeScript SDK v2
• 模型上下文协议规范

许可证

MIT