Meta Agent Tools
PT

Back to the catalog

MyFatoorah MCP

Safely connect AI agents to MyFatoorah payments, invoices, payment methods, and refunds.

Open source Open in the app JSON README (API)

About

Safely connect AI agents to MyFatoorah payments, invoices, payment methods, and refunds.

Details

Kind
MCP servers
Topic
Finance & crypto
Publisher
kuwaitdevs
Origin
official
Category
ferramentas
Transport
local
Version
0.1.0
Last push
2026-08-27T11:06:24Z
Repository state
ativo
Language
TypeScript
License
MIT
Added
2026-08-29 04:00:22
Updated
2026-08-29 04:00:22
Origin id
io.github.kuwaitdevs/myfatoorah-mcp

README

# MyFatoorah MCP

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

> 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](docs/USAGE.md).

## Requirements

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

## Setup

```sh
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:

```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):

```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

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

```sh
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](https://docs.myfatoorah.com/docs/api-key)
- [MCP TypeScript SDK v2](https://ts.sdk.modelcontextprotocol.io/v2/)
- [Model Context Protocol specification](https://modelcontextprotocol.io/specification/latest)

## License

MIT

More