M-Pesa Daraja

Safaricom の Daraja API をツールとして公開する MCP サーバーです。エージェント（Claude Code、Codex、Cursor、Gemini CLI、あらゆる MCP クライアント）からチャットで支払いを受け付けたり、支払いが完了したか確認したり、M-Pesa を操作したりできます。最初はサンドボックスで動作し、切り替えるまでは実環境での処理は行われません。

同じキットに含まれる Agent Skills と連携します。スキルは M-Pesa の統合方法をエージェントに教え、このサーバーは Daraja API の呼び出しを可能にします。どちらか一方だけでも利用できます。

対象ユーザー

• 決済統合を構築する開発者：エージェントにサンドボックスへのリクエスト送信を依頼し、実際の応答を確認できます。
• Daraja API の仕組みを学ぶ方：安全なテスト環境に実際のリクエストを送信し、返される内容を確認できます。
• AI エージェントに決済を任せたい企業やチーム：支払いの受け付け、完了状況の確認、照合をエージェントに任せられます。

インストール

エージェントにインストールを任せる方法。 以下を Claude Code、Codex、Cursor、Gemini CLI、または任意のコーディングエージェントに貼り付けます。

Add the M-Pesa Daraja MCP server to yourself, named "mpesa", with the command: uvx mpesa-daraja-mcp
It needs no keys in your config. If uv is missing, tell me how to install it first.
Don't ask me for my Daraja keys. Tell me to run `uvx mpesa-daraja-mcp setup` in my own terminal,
which saves them privately, then to restart you.
After I restart you, call mpesa_check_credentials and tell me if everything works.

自分でインストールする方法。 uv が必要です。ウィザードでは Daraja のキーを入力します（シークレットは非表示で入力されます）。Safaricom に接続してキーを検証し、自分だけが読み取れるファイルに保存したうえで、Claude Code、Codex、Gemini CLI、または Cursor にサーバーを登録します。

uvx mpesa-daraja-mcp setup

次にエージェントを再起動し、次のように依頼します：「M-Pesa の認証情報を確認してから、0712345678 に KES 1 の STK プッシュを送り、支払いが完了したら教えてください。」 スキルやその他の例を含む Agent Kit の全体は、メイン README をご覧ください。

ツール

ツール	Daraja API	資金の移動
mpesa_explain_code	— オフラインでのエラー／結果コード検索
mpesa_normalize_phone	— オフラインでの 07… → 2547… 変換
mpesa_generate_stk_password	— オフラインでの Password と EAT Timestamp の生成
mpesa_parse_callback	— あらゆるコールバックペイロードのオフライン解析
mpesa_setup_status	— オフライン：ツールセットごとに設定済みの項目と不足している項目を確認（値は表示しません）
mpesa_check_credentials	OAuth トークン（返されません）
mpesa_get_result	冪等性キーまたは任意の Daraja ID による最終ステータス（取得済みコールバックから確認。STK の場合は STK Query にフォールバック）
mpesa_stk_push_and_wait	M-Pesa Express：プッシュ後、コールバックを待機／クエリをポーリング。SUCCESS、FAILED、UNKNOWN を返します	✅
mpesa_stk_push / mpesa_stk_query	M-Pesa Express、実行後は待機しない／ステータス	✅ /
mpesa_c2b_register_urls / mpesa_c2b_simulate	C2B v2（simulate はサンドボックスのみ）
mpesa_pull_transactions	Pull Transactions クエリ
mpesa_b2c_payment	B2C v3、B2Pochi	✅
mpesa_b2b_payment	BusinessPayBill、BusinessBuyGoods、BusinessPayToBulk（B2C トップアップ）、PayTaxToKRA	✅
mpesa_b2b_express_checkout	B2B USSD プッシュ	✅
mpesa_transaction_status / mpesa_account_balance	ステータス／残高（非同期結果）
mpesa_reverse_transaction	取り消し	✅
mpesa_generate_dynamic_qr	ダイナミック QR を PNG ファイルとして保存（画像ではなくパスを返します）
mpesa_ratiba_create_standing_order	M-Pesa Ratiba	✅
mpesa_bill_manager_optin / mpesa_bill_manager_send_invoice / mpesa_bill_manager_cancel_invoice	Bill Manager

ツールの注釈では、資金を移動するツールに destructiveHint が付与されるため、MCP クライアントは承認を求めます。

安全性

• デフォルトではサンドボックスを使用します。
• 本番環境では、DARAJA_ALLOW_LIVE_MONEY_MOVEMENT=true が設定されていない限り、送金ツールは実行を拒否します。
• コールバック URL は HTTPS である必要があります。また、URL に mpesa／safaricom が含まれる C2B URL は事前に拒否されます。
• トークンやシークレットがツールの出力に返されることはありません。
• ResponseCode "0" を含むレスポンスには _note: ACCEPTED for processing only のタグが付くため、エージェントは支払いが完了したと報告しません。
• 冪等性のある送金ツール。 各リクエストは冪等性キーに紐付けて保存されます。同じキーを再度使用すると、再度送金する代わりに保存済みのリクエストが返されます（duplicate: true）。
  • 確実に FAILED と判定されたリクエストのみ再送されます。
  • ACCEPTED または UNKNOWN のリクエスト（キューのタイムアウト、ネットワークエラー）は、結果が判明するまで再送されません。
  • B2C、B2B、B2B Express では、refund-order-1042 のような明示的な idempotency_key が必要です。Reversal、tax、Ratiba では、それぞれトランザクション ID、PRN、電話番号と名前からキーが生成されます。STK ではキーは任意です。

設定

変数	必須	備考
DARAJA_ENV		sandbox（デフォルト）または production
DARAJA_CONSUMER_KEY, DARAJA_CONSUMER_SECRET	✅	Daraja アプリから取得します
DARAJA_SHORTCODE	多くのツールで必要	Paybill／店舗番号（サンドボックスでは 174379）
DARAJA_PASSKEY	STK	Lipa na M-Pesa のパスキー
DARAJA_INITIATOR_NAME	B2C/B2B/status/balance/reversal	API オペレーターのユーザー名
DARAJA_SECURITY_CREDENTIAL	同上	事前に暗号化された認証情報、または次の 2 つを設定
DARAJA_INITIATOR_PASSWORD + DARAJA_CERT_PATH		サーバーは起動時に証明書を使ってパスワードを暗号化します
DARAJA_CALLBACK_BASE_URL		例：https://abc.ngrok-free.app。ツールが /mpesa/stk/callback、/mpesa/b2c/result などを追加します
DARAJA_ALLOW_LIVE_MONEY_MOVEMENT		本番環境での請求／支払いを許可するには true
DARAJA_CALLBACK_LISTEN		例：127.0.0.1:8787。組み込みのコールバック受信サーバーを起動します
DARAJA_CALLBACK_TOKEN	受信サーバーを使う場合	16 文字以上のランダム文字列。コールバック URL は <base>/cb/<token>/… になります
DARAJA_STATE_DB		リクエストと結果を保存する SQLite ファイル（デフォルト：~/.mpesa-mcp/state.db）
DARAJA_TOOLSETS		stk,c2b,payouts,ops,qr,ratiba,billmanager のカンマ区切りリスト（core は常に有効）。デフォルト：すべて
DARAJA_OUTPUT_DIR		QR PNG の保存先（デフォルト：~/.mpesa-mcp/qr）

コマンドと設定ファイル

uvx mpesa-daraja-mcp setup     # guided: keys (hidden input), live check, save, register with your agents
uvx mpesa-daraja-mcp status    # what's configured (masked) + a live key check
uvx mpesa-daraja-mcp           # the MCP server itself, on stdio: what your agent runs

エージェントの設定で、サーバーにフラグや環境変数を指定する必要はありません。設定は次の順序で読み込まれます（上にあるものほど優先されます）。

1. 環境変数。例：クライアントの env ブロックで設定されたもの。
2. プロジェクトの .env。エージェントがサーバーを起動するフォルダーにあるファイル、または DARAJA_DOTENV で指定されたファイルです。DARAJA_* 行のみが読み込まれます。
3. ユーザー設定ファイル。setup が書き込むファイルです：~/.config/mpesa-daraja-mcp/config.env（Windows：%APPDATA%\mpesa-daraja-mcp\config.env。フォルダーは DARAJA_CONFIG_DIR で変更できます）。このファイルは本人のみが読み取れます。

設定がない場合でもサーバーは起動します。その場合、ツールが不足している設定を説明し、mpesa_setup_status が値を公開することなく各ツールセットの不足項目を一覧表示します。

手動で登録する場合：claude mcp add --scope user mpesa -- uvx mpesa-daraja-mcp。その他のエージェントについては、docs/clients.md をご覧ください。以前の mpesa-mcp コマンドも引き続き使用できます。

結果とコールバック

すべての送金ツールまたは非同期ツールは、次の形式で結果を返します。

{"status": "ACCEPTED | SUCCESS | FAILED | UNKNOWN", "message": "...", "idempotency_key": "...",
 "duplicate": false, "ids": {"checkout_request_id": "..."}, "receipt": "...", "result_code": "...",
 "explanation": "...", "raw": {}}

エージェントが最終結果を確認できるようにするには、組み込みの受信サーバーを有効にします。

export DARAJA_CALLBACK_LISTEN=127.0.0.1:8787
export DARAJA_CALLBACK_TOKEN=$(python -c "import secrets; print(secrets.token_urlsafe(24))")
ngrok http 8787                        # sandbox; use a reverse proxy with TLS in production
export DARAJA_CALLBACK_BASE_URL=https://<tunnel-host>

コールバックは DARAJA_STATE_DB に保存されます。

• mpesa_get_result(id) で読み取れます。
• mpesa_stk_push_and_wait は 1 回の呼び出しで最終結果を返します。
• キューのタイムアウトによるコールバックは UNKNOWN として記録されます。
• C2B の検証リクエストは常に受け入れられます。支払いを拒否する必要がある場合は、独自の受信サーバーを使用してください。

受信サーバーがなくても、mpesa_stk_push_and_wait は STK Query を通じて動作します。その他の API では、受信したペイロードを mpesa_parse_callback に貼り付けてください。

必要なツールだけを読み込む

サーバーが提供する各ツールは、呼び出されない場合でもエージェントのコンテキストを消費します。使用するグループを DARAJA_TOOLSETS に設定すると、エージェントにはそのツールだけが表示されます。基本ツール（core）は常に有効です。設定を解除すると、すべてのツールが読み込まれます。

設定	利用できるもの	適した用途
未設定（デフォルト）	24 個すべてのツール	すべてを試す
stk	基本ツールと 3 つの STK Push ツール	STK 決済のみを受け付ける店舗
stk,payouts	上記に加え、B2C、B2B、B2B Express	決済の受け付けと払い出しを行うプラットフォーム
stk,c2b,ops	STK、C2B、さらに取引状況、残高、取消	照合とサポート

グループは stk、c2b、payouts、ops、qr、ratiba、billmanager です。

開発

pip install -e ".[dev]"
pytest

テストでは respx を使って Daraja をモックします。ネットワークには一切アクセスしません。

ライセンス

MIT © 2026 Mr-Macharia。独立したオープンソースプロジェクトであり、Safaricom PLC と提携しておらず、同社の承認も受けていません。M-Pesa と Daraja は Safaricom PLC の商標です。