MyFatoorah MCP

MyFatoorah MCP

MyFatoorah API 向けの、LLM に適した Model Context Protocol サーバーです。Claude、VS Code、Cursor、その他の MCP ホストから、決済方法の確認、支払いリンクの作成、支払いの検証、請求書の確認、返金の管理を、それぞれに特化したツールを通じて行えます。

これは独立したコミュニティプロジェクトであり、MyFatoorah の公式製品ではありません。ライブアカウントで使用する前に、サンドボックスでテストしてください。

ホストのセットアップ、Inspector のテスト、エージェントプロンプト、支払いの検証、返金、トラブルシューティングについては、使用ガイドをご覧ください。

要件

• Node.js 20 以降
• 使用するツールに必要な権限だけを持つ MyFatoorah API トークン

セットアップ

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

MCP ホストの環境に MYFATOORAH_API_TOKEN を設定してください。サーバーは .env を自動的に読み込みません。VS Code のデバッグ構成では読み込みます。

環境変数

変数	必須	デフォルト	説明
MYFATOORAH_API_TOKEN	API 呼び出し時に必須	—	Bearer トークンです。エージェントプロンプトに公開しないでください。
MYFATOORAH_ENVIRONMENT	いいえ	test	test、kuwait、uae、saudi_arabia、qatar、または egypt
MYFATOORAH_BASE_URL	いいえ	環境 URL	対応する MyFatoorah のデプロイ環境またはテストプロキシ用の HTTPS オーバーライド
MYFATOORAH_TIMEOUT_MS	いいえ	30000	1～300000 ミリ秒のリクエストタイムアウト

Kuwait には、共通の Bahrain、Jordan、Oman の API オリジンも含まれます。複数の国のアカウントでは、国ごとに別のトークンを使用します。

MCP ホストを接続する

ホスト構成では絶対パスを使用してください。/absolute/path/to/myfatoorah-mcp とトークンのプレースホルダーは、ローカル環境に合わせて置き換えてください。

Claude Desktop

このサーバーを Claude Desktop の MCP 構成に追加します。

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

構成を保存した後、Claude Desktop を再起動してください。

Claude Code

プロジェクト単位の構成には .mcp.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

付属の .vscode/mcp.json は、ビルド済みサーバーを起動し、トークンを安全に入力するよう求めます。一度ビルドし、MCP サーバービューを開いてから myfatoorah を起動してください。トークンはリポジトリに保存されません。

Cursor および汎用 stdio ホスト

Claude Desktop の例と同じ command、args、env の値を使用してください。MCP プロトコルのメッセージには stdin/stdout を使用します。サーバーの診断情報は stderr に出力する必要があります。

npm に公開した後は、ホストから npx -y myfatoorah-mcp を使用して起動することもできます。

ツール

ツール	効果	目的
myfatoorah_get_payment_methods	読み取り専用	有効な決済方法とその ApiName の値を一覧表示します
myfatoorah_create_payment	データを作成	POST /v3/payments を使用して、ホスト型チェックアウトまたは請求書リンクを作成します
myfatoorah_get_payment	読み取り専用	PaymentId を指定して、正式な決済の詳細を取得します
myfatoorah_get_invoice	読み取り専用	InvoiceId または外部識別子を指定して、請求書を取得します
myfatoorah_create_refund	破壊的	全額または一部の払い戻しを作成します。confirm: true が必要です
myfatoorah_get_refund	読み取り専用	RefundId を指定して、払い戻しの詳細を取得します
myfatoorah_api_request	さまざま	相対 /v2/ または /v3/ パスに限定した緊急用の手段です。変更操作には確認が必要です

このサーバーは、以下も公開します。

• リソース myfatoorah://configuration：環境、ベース URL、タイムアウト、トークンが設定されているかどうかを提供します。トークン自体は公開しません。
• プロンプト create-payment-safely：決済リンクの作成を案内する再利用可能なワークフローです。

成功したツール呼び出しは、簡潔なテキスト要約に加えて、MyFatoorah の応答を含む機械可読な structuredContent を返します。

安全な決済ワークフロー

1. myfatoorah://configuration を読み取り、テスト環境か本番環境かを確認します。
2. ゲートウェイを選択する場合は、myfatoorah_get_payment_methods を呼び出し、その ApiName を使用します。
3. 金額、通貨、顧客、通知方法、コールバック URL を確認します。
4. myfatoorah_create_payment を呼び出し、顧客に PaymentURL を案内します。
5. コールバック後、返された PaymentId を指定して myfatoorah_get_payment を呼び出します。リダイレクトは支払いの証明ではありません。請求書のステータスが PAID、取引のステータスが SUCCESS であることを必ず確認してください。

本番環境では、払い戻しによって資金が移動します。confirm: true を渡す前に、対象の PaymentId と金額についてユーザーから明示的な承認を得てください。

開発

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

npm run inspect は、コンパイル済みの stdio サーバーに対して公式の MCP Inspector を起動します。VS Code には、ビルド／テストタスクとデバッグ設定も含まれています。

テストでは、すべての MyFatoorah リクエストをモックします。ネットワーク呼び出しは行わず、トークンも必要ありません。

セキュリティ

• 最小権限の MyFatoorah API キーを使用し、定期的にローテーションしてください。
• 認証情報はホスト環境またはシークレットマネージャーに保管し、ソース管理やモデルコンテキストには決して含めないでください。
• 汎用リクエストツールは、認証情報の流出を防ぐため、絶対 URL、プロトコル相対 URL、パストラバーサル、および /v2/ と /v3/ 以外のパスを拒否します。
• API エラーと Bearer 値は、モデルに渡される前にマスキングされます。
• 対応する変更操作では冪等性キーを優先し、安定した注文識別子を使用してください。
• この stdio プロセスを、認証なしのネットワークサービスとして公開しないでください。
• カード情報を直接扱う機能は、特化したツールとして意図的に提供していません。PCI 準拠が必要です。

API の範囲と参考資料

特化したツールは、2026 年 8 月時点で文書化されている MyFatoorah の v3 ルートを使用します。

• 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}

参考資料：

• MyFatoorah API キーと地域別 URL
• MCP TypeScript SDK v2
• Model Context Protocol の仕様

ライセンス

MIT