MyFatoorah MCP

Ein LLM-freundlicher Model Context Protocol-Server für die MyFatoorah API. Er ermöglicht Claude, VS Code, Cursor und anderen MCP-Hosts, Zahlungsmethoden zu entdecken, Zahlungslinks zu erstellen, Zahlungen zu verifizieren, Rechnungen zu prüfen und Rückerstattungen über fokussierte Tools zu verwalten.

Dies ist ein unabhängiges Community-Projekt, kein offizielles MyFatoorah-Produkt. Testen Sie in der Sandbox, bevor Sie ein Live-Konto verwenden.

Schritt-für-Schritt-Anleitungen für die Host-Einrichtung, Inspector-Tests, Agent-Prompts, Zahlungsverifizierung, Rückerstattungen und Fehlerbehebung finden Sie im Nutzungsleitfaden.

Anforderungen

• Node.js 20 oder neuer

• Ein MyFatoorah-API-Token mit nur den Berechtigungen, die für die von Ihnen verwendeten Tools erforderlich sind

Related MCP server: AgentPay

Einrichtung

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

Setzen Sie MYFATOORAH_API_TOKEN in der Umgebung des MCP-Hosts. Der Server lädt .env nicht automatisch; die Debugkonfiguration von VS Code tut dies.

Umgebungsvariablen

Kuwait deckt auch den gemeinsamen API-Origin von Bahrain, Jordanien und Oman ab. Mehrländer-Konten verwenden für jedes Land ein separates Token.

MCP-Host verbinden

Verwenden Sie in Host-Konfigurationen einen absoluten Pfad. Ersetzen Sie /absolute/path/to/myfatoorah-mcp und den Token-Platzhalter lokal.

Claude Desktop

Fügen Sie diesen Server zur MCP-Konfiguration von Claude Desktop hinzu:

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

Starten Sie Claude Desktop neu, nachdem Sie die Konfiguration gespeichert haben.

Claude Code

Projektbezogene Konfiguration kann .mcp.json verwenden (committen Sie sie nicht, wenn sie ein Token enthält):

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

Die enthaltene .vscode/mcp.json startet den gebauten Server und fragt sicher nach einem Token. Bauen Sie einmal, öffnen Sie die MCP-Server-Ansicht und starten Sie dann myfatoorah. Das Token wird nicht im Repository gespeichert.

Cursor und generische Stdio-Hosts

Verwenden Sie dieselben Werte für command, args und env wie im Beispiel für Claude Desktop. MCP-Protokollnachrichten verwenden stdin/stdout; Serverdiagnosen müssen stderr verwenden.

Nach der Veröffentlichung auf npm können Hosts es stattdessen mit npx -y myfatoorah-mcp starten.

Tools

Der Server stellt außerdem bereit:

• Ressource myfatoorah://configuration: Umgebung, Basis-URL, Timeout und ob ein Token konfiguriert ist – niemals das Token selbst.

• Prompt create-payment-safely: ein wiederverwendbarer geführter Workflow für Zahlungslinks.

Erfolgreiche Tools geben eine knappe Textzusammenfassung sowie maschinenlesbares structuredContent zurück, das die MyFatoorah-Antwort enthält.

Sicherer Zahlungsworkflow

1. Lesen Sie myfatoorah://configuration und bestätigen Sie, ob es sich um Test oder Live handelt.

2. Wenn Sie ein Gateway auswählen, rufen Sie myfatoorah_get_payment_methods auf und verwenden Sie dessen ApiName.

3. Bestätigen Sie Betrag, Währung, Kunde, Benachrichtigungsmethode und Callback-URL.

4. Rufen Sie myfatoorah_create_payment auf und geben Sie dem Kunden dessen PaymentURL.

5. Rufen Sie nach dem Callback myfatoorah_get_payment mit der zurückgegebenen PaymentId auf. Eine Weiterleitung ist kein Zahlungsnachweis; verlangen Sie den Rechnungsstatus PAID und den Transaktionsstatus SUCCESS.

Rückerstattungen bewegen im Live-Modus Geld. Holen Sie die ausdrückliche Genehmigung des Benutzers für die genaue PaymentId und den Betrag ein, bevor Sie confirm: true übergeben.

Entwicklung

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

npm run inspect startet den offiziellen MCP Inspector gegen den kompilierten Stdio-Server. VS Code enthält außerdem Build-/Test-Aufgaben und eine Debugkonfiguration.

Tests mocken jede MyFatoorah-Anfrage; sie tätigen keine Netzwerkaufrufe und benötigen kein Token.

Sicherheit

• Verwenden Sie einen MyFatoorah-API-Schlüssel mit geringstmöglichen Rechten und rotieren Sie ihn regelmäßig.

• Legen Sie Anmeldedaten in der Host-Umgebung oder in einem Secret-Manager ab, niemals in der Versionskontrolle oder im Modellkontext.

• Das generische Anfragetool lehnt absolute URLs, protokollrelative URLs, Traversal und Pfade außerhalb von /v2/ und /v3/ ab, um die Exfiltration von Anmeldedaten zu verhindern.

• API-Fehler und Bearer-Werte werden geschwärzt, bevor sie das Modell erreichen.

• Bevorzugen Sie Idempotenzschlüssel für unterstützte Mutationen und stabile Bestellkennungen.

• Stellen Sie diesen Stdio-Prozess nicht als unauthentifizierten Netzwerkdienst bereit.

• Die direkte Kartenverarbeitung ist absichtlich nicht als fokussiertes Tool modelliert; sie erfordert PCI-Konformität.

API-Umfang und Referenzen

Die fokussierten Tools verwenden die dokumentierten v3-Routen von MyFatoorah (Stand 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}

Referenzen:

• MyFatoorah-API-Schlüssel und regionale URLs

• MCP TypeScript SDK v2

• Model Context Protocol Spezifikation

Lizenz

MIT