MyFatoorah MCP

一个对 LLM 友好的 Model Context Protocol 服务器，用于 MyFatoorah API。它让 Claude、VS Code、Cursor 以及其他 MCP 主机能够通过专用工具发现支付方式、创建支付链接、验证支付、查看发票以及管理退款。

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

有关分步主机设置、Inspector 测试、智能体提示词、支付验证、退款和故障排查，请参阅使用指南。

要求

• Node.js 20 或更高版本

• 一个 MyFatoorah API 令牌，仅需包含你所使用工具要求的权限

Related MCP server: AgentPay

设置

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

在 MCP 主机的环境中设置 MYFATOORAH_API_TOKEN。服务器不会自动加载 .env 文件；VS Code 的调试配置会加载。

环境变量

科威特环境还覆盖巴林、约旦和阿曼共用的 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://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 范围与参考

这些专用工具使用 MyFatoorah 文档中截至 2026 年 8 月的 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

• Model Context Protocol 规范

许可证

MIT