MyFatoorah MCP

An LLM-friendly Model Context Protocol server for the MyFatoorah API. It lets Claude, VS Code, Cursor, and other MCP hosts discover payment methods, create payment links, verify payments, inspect invoices, and manage refunds through focused tools.

This is an independent community project, not an official MyFatoorah product. Test in the sandbox before using a live account.

For step-by-step host setup, Inspector testing, agent prompts, payment verification, refunds, and troubleshooting, see the usage guide.

Requirements

• Node.js 20 or newer
• A MyFatoorah API token with only the permissions required by the tools you use

Setup

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

Set MYFATOORAH_API_TOKEN in the MCP host's environment. The server does not automatically load .env; the VS Code debug configuration does.

Environment variables

| Variable | Required | Default | Description | | ------------------------ | ------------------------- | --------------- | ------------------------------------------------------------------ | | MYFATOORAH_API_TOKEN | Yes, when calling the API | — | Bearer token. Never expose it to an agent prompt. | | MYFATOORAH_ENVIRONMENT | No | test | test, kuwait, uae, saudi_arabia, qatar, or egypt | | MYFATOORAH_BASE_URL | No | Environment URL | HTTPS override for a supported MyFatoorah deployment or test proxy | | MYFATOORAH_TIMEOUT_MS | No | 30000 | Request timeout from 1 to 300000 ms |

Kuwait also covers the shared Bahrain, Jordan, and Oman API origin. Multi-country accounts use a separate token for each country.

Connect an MCP host

Use an absolute path in host configurations. Replace /absolute/path/to/myfatoorah-mcp and the token placeholder locally.

Claude Desktop

Add this server to Claude Desktop's MCP configuration:

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

Restart Claude Desktop after saving the configuration.

Claude Code

Project-scoped configuration can use .mcp.json (keep it uncommitted if it contains a token):

{
  "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

The included .vscode/mcp.json launches the built server and securely prompts for a token. Build once, open the MCP servers view, then start myfatoorah. The token is not stored in the repository.

Cursor and generic stdio hosts

Use the same command, args, and env values as the Claude Desktop example. MCP protocol messages use stdin/stdout; server diagnostics must use stderr.

After publishing to npm, hosts can instead launch it with npx -y myfatoorah-mcp.

Tools

| Tool | Effect | Purpose | | -------------------------------- | ------------ | ------------------------------------------------------------------------------------------- | | myfatoorah_get_payment_methods | Read-only | Lists enabled methods and their ApiName values | | myfatoorah_create_payment | Creates data | Creates a hosted checkout or invoice link with POST /v3/payments | | myfatoorah_get_payment | Read-only | Gets authoritative payment details by PaymentId | | myfatoorah_get_invoice | Read-only | Gets an invoice by InvoiceId or external identifier | | myfatoorah_create_refund | Destructive | Creates a full or partial refund; requires confirm: true | | myfatoorah_get_refund | Read-only | Gets refund details by RefundId | | myfatoorah_api_request | Varies | Restricted escape hatch for relative /v2/ or /v3/ paths; mutations require confirmation |

The server also exposes:

• Resource myfatoorah://configuration: environment, base URL, timeout, and whether a token is configured—never the token itself.
• Prompt create-payment-safely: a reusable guided payment-link workflow.

Successful tools return a concise text summary plus machine-readable structuredContent containing the MyFatoorah response.

Safe payment workflow

1. Read myfatoorah://configuration and confirm test versus live.
2. If selecting a gateway, call myfatoorah_get_payment_methods and use its ApiName.
3. Confirm amount, currency, customer, notification method, and callback URL.
4. Call myfatoorah_create_payment and give the customer its PaymentURL.
5. After callback, call myfatoorah_get_payment with the returned PaymentId. A redirect is not proof of payment; require invoice status PAID and transaction status SUCCESS.

Refunds move money in live mode. Obtain explicit user approval for the exact PaymentId and amount before passing confirm: true.

Development

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

npm run inspect starts the official MCP Inspector against the compiled stdio server. VS Code also includes build/test tasks and a debug configuration.

Tests mock every MyFatoorah request; they do not make network calls or require a token.

Security

• Use a least-privilege MyFatoorah API key and rotate it regularly.
• Put credentials in the host environment or a secret manager, never source control or model context.
• The generic request tool rejects absolute URLs, protocol-relative URLs, traversal, and paths outside /v2/ and /v3/ to prevent credential exfiltration.
• API errors and Bearer values are redacted before reaching the model.
• Prefer idempotency keys for supported mutations and stable order identifiers.
• Do not expose this stdio process as an unauthenticated network service.
• Direct card handling is intentionally not modeled as a focused tool; it requires PCI compliance.

API scope and references

The focused tools use MyFatoorah's documented v3 routes as of August 2026:

• 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}

References:

• MyFatoorah API key and regional URLs
• MCP TypeScript SDK v2
• Model Context Protocol specification

License

MIT