Skip to main content
Glama
MyFatoorah MCP

MyFatoorah MCP

by kuwaitdevs

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

Related MCP server: pai

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:

License

MIT

Available Tools

7 tools
myfatoorah_api_requestAdvanced MyFatoorah API requestA
Destructive

Escape hatch for documented MyFatoorah v2/v3 endpoints not covered by another tool. Accepts only safe relative /v2/ or /v3/ paths and GET, POST, or PUT. Absolute URLs are blocked so credentials cannot be sent elsewhere. POST/PUT require confirm=true.

Inputs: path (required), body, method, confirm, +1 more. Returns: response

myfatoorah_create_paymentCreate MyFatoorah payment or invoice linkA

Creates a payment/invoice using POST /v3/payments. In a live environment this creates a real payable invoice. Omit paymentMethod to show all enabled methods; use notificationOption for invoicing. The returned PaymentURL is where the customer pays.

Inputs: amount (required), advanced, currency, customer, +11 more. Returns: response

myfatoorah_create_refundCreate a MyFatoorah refundA
Destructive

Creates a real full or partial refund using POST /v3/refunds. This moves money in live environments. Call only after the user explicitly approves the exact PaymentId and amount; confirm must be true.

Inputs: amount (required), confirm (required), paymentId (required), comment, +4 more. Returns: response

myfatoorah_get_invoiceGet MyFatoorah invoiceA
Read-onlyIdempotent

Gets an invoice by exactly one lookup type. Invoice ID uses /v3/invoices/{value}; external identifier returns the most recent matching invoice and uses /v3/invoices/externalIdentifier/{value}.

Inputs: value (required), lookupBy (required). Returns: response

myfatoorah_get_paymentGet MyFatoorah payment detailsA
Read-onlyIdempotent

Gets authoritative payment details by PaymentId using GET /v3/payments/{paymentId}. Treat payment as successful only when Invoice.Status is PAID and Transaction.Status is SUCCESS.

Inputs: paymentId (required). Returns: response

myfatoorah_get_payment_methodsGet MyFatoorah payment methodsA
Read-onlyIdempotent

List payment methods enabled for this account. Read ApiName from the result and pass it as paymentMethod when creating a hosted payment.

Inputs: no named parameters. Returns: response

myfatoorah_get_refundGet MyFatoorah refund detailsA
Read-onlyIdempotent

Gets a refund by RefundId using GET /v3/refunds/{refundId}. Refund statuses include Refunded, Canceled, and Pending.

Inputs: refundId (required). Returns: response

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each core tool targets a distinct resource and action: payment methods, payments, invoices, and refunds are clearly separated. The api_request escape hatch is explicitly scoped to endpoints not covered by the other tools, so it complements rather than overlaps with them.

    Naming Consistency4/5

    Six tools consistently follow the myfatoorah_verb_noun pattern, which is predictable and readable. The only deviation is myfatoorah_api_request, a noun-style escape hatch, which is a minor exception rather than a systemic inconsistency.

    Tool Count5/5

    Seven tools is well-scoped for a payment-focused server: it covers payment methods, payment creation/retrieval, invoice retrieval, refund creation/retrieval, plus one generic escape hatch. Every tool earns its place, and the count is neither bloated nor too thin.

    Completeness4/5

    The set covers the core payment workflow: create payment, check payment status, retrieve invoice, create refund, and check refund status. It lacks explicit cancel/update/list operations, but the api_request escape hatch covers documented endpoints not individually modeled, so agents are not left with a hard dead end.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents to manage API keys and child keys with budgets and spending caps, set plans and model routing, handle wallet payments and top-ups, and verify signed receipts through MCP tools.
      265 npm
      2
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to perform and manage payments through the Model Context Protocol, including paying, checking balances and history, registering bots, setting spending limits, discovering supported networks and tokens, inspecting commissions, and managing bot pools. It also supports governed tool calls with policy decisions, human approval, and tamper-evident audit traces.
      12
      Apache 2.0