{
  "markdown": "# MyFatoorah MCP\n\nAn LLM-friendly [Model Context Protocol](https://modelcontextprotocol.io/) server for the [MyFatoorah API](https://docs.myfatoorah.com/docs/). 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.\n\n> This is an independent community project, not an official MyFatoorah product. Test in the sandbox before using a live account.\n\nFor step-by-step host setup, Inspector testing, agent prompts, payment verification, refunds, and troubleshooting, see the [usage guide](docs/USAGE.md).\n\n## Requirements\n\n- Node.js 20 or newer\n- A MyFatoorah API token with only the permissions required by the tools you use\n\n## Setup\n\n```sh\nnpm install\ncp .env.example .env\nnpm run build\n```\n\nSet `MYFATOORAH_API_TOKEN` in the MCP host's environment. The server does not automatically load `.env`; the VS Code debug configuration does.\n\n### Environment variables\n\n| Variable                 | Required                  | Default         | Description                                                        |\n| ------------------------ | ------------------------- | --------------- | ------------------------------------------------------------------ |\n| `MYFATOORAH_API_TOKEN`   | Yes, when calling the API | —               | Bearer token. Never expose it to an agent prompt.                  |\n| `MYFATOORAH_ENVIRONMENT` | No                        | `test`          | `test`, `kuwait`, `uae`, `saudi_arabia`, `qatar`, or `egypt`       |\n| `MYFATOORAH_BASE_URL`    | No                        | Environment URL | HTTPS override for a supported MyFatoorah deployment or test proxy |\n| `MYFATOORAH_TIMEOUT_MS`  | No                        | `30000`         | Request timeout from 1 to 300000 ms                                |\n\nKuwait also covers the shared Bahrain, Jordan, and Oman API origin. Multi-country accounts use a separate token for each country.\n\n## Connect an MCP host\n\nUse an absolute path in host configurations. Replace `/absolute/path/to/myfatoorah-mcp` and the token placeholder locally.\n\n### Claude Desktop\n\nAdd this server to Claude Desktop's MCP configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"myfatoorah\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/myfatoorah-mcp/dist/index.js\"],\n      \"env\": {\n        \"MYFATOORAH_API_TOKEN\": \"YOUR_TOKEN\",\n        \"MYFATOORAH_ENVIRONMENT\": \"test\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop after saving the configuration.\n\n### Claude Code\n\nProject-scoped configuration can use `.mcp.json` (keep it uncommitted if it contains a token):\n\n```json\n{\n  \"mcpServers\": {\n    \"myfatoorah\": {\n      \"type\": \"stdio\",\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/myfatoorah-mcp/dist/index.js\"],\n      \"env\": {\n        \"MYFATOORAH_API_TOKEN\": \"YOUR_TOKEN\",\n        \"MYFATOORAH_ENVIRONMENT\": \"test\"\n      }\n    }\n  }\n}\n```\n\n### VS Code / GitHub Copilot\n\nThe 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.\n\n### Cursor and generic stdio hosts\n\nUse the same `command`, `args`, and `env` values as the Claude Desktop example. MCP protocol messages use stdin/stdout; server diagnostics must use stderr.\n\nAfter publishing to npm, hosts can instead launch it with `npx -y myfatoorah-mcp`.\n\n## Tools\n\n| Tool                             | Effect       | Purpose                                                                                     |\n| -------------------------------- | ------------ | ------------------------------------------------------------------------------------------- |\n| `myfatoorah_get_payment_methods` | Read-only    | Lists enabled methods and their `ApiName` values                                            |\n| `myfatoorah_create_payment`      | Creates data | Creates a hosted checkout or invoice link with `POST /v3/payments`                          |\n| `myfatoorah_get_payment`         | Read-only    | Gets authoritative payment details by PaymentId                                             |\n| `myfatoorah_get_invoice`         | Read-only    | Gets an invoice by InvoiceId or external identifier                                         |\n| `myfatoorah_create_refund`       | Destructive  | Creates a full or partial refund; requires `confirm: true`                                  |\n| `myfatoorah_get_refund`          | Read-only    | Gets refund details by RefundId                                                             |\n| `myfatoorah_api_request`         | Varies       | Restricted escape hatch for relative `/v2/` or `/v3/` paths; mutations require confirmation |\n\nThe server also exposes:\n\n- Resource `myfatoorah://configuration`: environment, base URL, timeout, and whether a token is configured—never the token itself.\n- Prompt `create-payment-safely`: a reusable guided payment-link workflow.\n\nSuccessful tools return a concise text summary plus machine-readable `structuredContent` containing the MyFatoorah response.\n\n## Safe payment workflow\n\n1. Read `myfatoorah://configuration` and confirm test versus live.\n2. If selecting a gateway, call `myfatoorah_get_payment_methods` and use its `ApiName`.\n3. Confirm amount, currency, customer, notification method, and callback URL.\n4. Call `myfatoorah_create_payment` and give the customer its `PaymentURL`.\n5. 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`.\n\nRefunds move money in live mode. Obtain explicit user approval for the exact PaymentId and amount before passing `confirm: true`.\n\n## Development\n\n```sh\nnpm run format\nnpm run lint\nnpm run typecheck\nnpm test\nnpm run build\nnpm run inspect\n```\n\n`npm run inspect` starts the official MCP Inspector against the compiled stdio server. VS Code also includes build/test tasks and a debug configuration.\n\nTests mock every MyFatoorah request; they do not make network calls or require a token.\n\n## Security\n\n- Use a least-privilege MyFatoorah API key and rotate it regularly.\n- Put credentials in the host environment or a secret manager, never source control or model context.\n- The generic request tool rejects absolute URLs, protocol-relative URLs, traversal, and paths outside `/v2/` and `/v3/` to prevent credential exfiltration.\n- API errors and Bearer values are redacted before reaching the model.\n- Prefer idempotency keys for supported mutations and stable order identifiers.\n- Do not expose this stdio process as an unauthenticated network service.\n- Direct card handling is intentionally not modeled as a focused tool; it requires PCI compliance.\n\n## API scope and references\n\nThe focused tools use MyFatoorah's documented v3 routes as of August 2026:\n\n- `GET /v3/payment-methods`\n- `POST /v3/payments`\n- `GET /v3/payments/{paymentId}`\n- `GET /v3/invoices/{invoiceId}`\n- `GET /v3/invoices/externalIdentifier/{externalIdentifier}`\n- `POST /v3/refunds`\n- `GET /v3/refunds/{refundId}`\n\nReferences:\n\n- [MyFatoorah API key and regional URLs](https://docs.myfatoorah.com/docs/api-key)\n- [MCP TypeScript SDK v2](https://ts.sdk.modelcontextprotocol.io/v2/)\n- [Model Context Protocol specification](https://modelcontextprotocol.io/specification/latest)\n\n## License\n\nMIT\n",
  "bytes": 7397,
  "sha": "be0062efb50bfbaf5d5bba53f86e34f749d6e60bffdeda540a658deff5c720be",
  "repo_slug": "kuwaitdevs/myfatoorah-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_kuwaitdevs_myfatoorah_mcp_27d87cdb/readme"
}