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

Terminal

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:

config.json

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

config.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

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

Read myfatoorah://configuration and confirm test versus live.
If selecting a gateway, call myfatoorah_get_payment_methods and use its ApiName.
Confirm amount, currency, customer, notification method, and callback URL.
Call myfatoorah_create_payment and give the customer its PaymentURL.
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

Terminal

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:

License

MIT