mpesa-mcp

mpesa-mcp

東アフリカのフィンテック API 向け MCP サーバー — M-Pesa（Safaricom Daraja）と Africa's Talking

AI エージェントが M-Pesa の決済を実行し、取引状況を確認し、SMS を送信し、20 以上のアフリカの通信ネットワークで通話時間をチャージできるようにします。

モデル

このサーバーは、いかなるモデルも推奨、認定、ベンチマークせず、get_model_hint() は互換性維持のためだけに残されています（中立的なガイダンスを返します）。ツールのスキーマに確実に従うモデルを使用し、まずサンドボックスでリハーサルを行い、金銭の移動やメッセージ送信を伴うすべての呼び出しを人が承認するようにしてください。ライブモードでは、これらのツールには confirm_send=true が必要で、上限が設定されています（MPESA_MAX_AMOUNT_KES、デフォルトは KES 100,000、MPESA_MAX_SMS_RECIPIENTS、デフォルトは 50）。

このプロジェクトの目的

M-Pesa は、アフリカにおいて PayPal よりも多くの取引を毎日処理しています。Africa's Talking は SMS と USSD を通じて、20 か国以上の基本的な携帯電話を使うユーザーにリーチしています。どちらにも MCP サーバーはありません。

そのため、今日構築されているすべての AI エージェント（Claude、GPT、Gemini、その他の MCP 対応ランタイム）は、カスタム統合作業なしでは M-Pesa の決済を実行したり、スワヒリ語の SMS を送信したりできません。

mpesa-mcp は pip install 1 つでこのギャップを埋めます。

ツール

ツール	説明
mpesa_stk_push	顧客の M-Pesa 携帯電話に STK Push の決済プロンプトを表示します
mpesa_stk_query	STK Push リクエストの状況を確認します
mpesa_transaction_status	レシート番号を指定して M-Pesa の取引を照会します
sms_send	アフリカのネットワークを通じて 1～1,000 人の宛先に SMS を送信します
airtime_send	任意の加入者に通話時間をチャージします（KES、NGN、GHS、UGX など）

対応範囲

• M-Pesa： ケニア（Safaricom Daraja v3）— STK Push、C2B、取引状況
• SMS／通話時間チャージ： Africa's Talking を通じて、ケニア、ナイジェリア、ガーナ、タンザニア、ウガンダ、ルワンダ、南アフリカなど、さらに 15 か国以上

Glama（ホスト型 MCP）

mpesa-mcp は Glama でホスト型 MCP サーバーとして利用できます：

セキュリティ：NSA の MCP ガイダンスとの対応（自己評価であり、認証済みではありません）

mpesa-mcp は、Model Context Protocol のセキュリティに関する NSA Artificial Intelligence Security Center のサイバーセキュリティ情報シートである NSA CSI U/OO/6030316-26（2026 年 5 月） に照らしてレビューされました。このシートはガイダンスであり、認証可能な規格ではありません。そのため、以下の表はこのプロジェクト独自の自己評価であり、監査や認証ではありません。

管理領域	このサーバーの対応
パラメーターの検証	ケニアの電話番号は正規化して検証されます。金額は正の値で、設定された上限内である必要があります
監査ログ	ツール呼び出しごとに構造化ログを 1 行記録します。電話番号は切り詰めた SHA-256 ハッシュとして記録し、その他の識別子は指定されたとおりに記録します。送金呼び出しの終了時には、その結果を記録する行が出力されます
支出制限	1 回の支払いの上限、セッションごとの予算、任意の送金先許可リスト、およびライブモードでの確認を必須としています（下記の「制限付き認可」を参照）
トークンのライフサイクル	Daraja OAuth トークンは有効期限とともにキャッシュされ、自動的に更新されます
エラー処理	Daraja API エラーは構造化された結果として返されます。予期しない例外は型のみをログに記録して再送出され、MCP フレームワークがクライアントに報告します
HTTPS	Daraja API の呼び出しにはすべて HTTPS を使用します
シークレット	ライブ用認証情報は環境変数から取得します。この README に記載された Safaricom サンドボックスのテスト用ショートコードとパスキーは公開済みの例であり、シークレットではありません

脆弱性の報告方法については、SECURITY.md を参照してください。

参照： NSA CSI_MCP_SECURITY.pdf（2026 年 5 月、UNCLASSIFIED）

インストール

pip install mpesa-mcp

または uvx で直接実行します。

uvx mpesa-mcp

設定

サーバーを起動する前に、以下の環境変数を設定してください。

# M-Pesa (Safaricom Daraja)
MPESA_CONSUMER_KEY=your_consumer_key
MPESA_CONSUMER_SECRET=your_consumer_secret
MPESA_SHORTCODE=174379               # sandbox test shortcode
MPESA_PASSKEY=your_passkey
MPESA_CALLBACK_URL=https://yourdomain.com/mpesa/callback
MPESA_SANDBOX=true                   # set false for production

# Africa's Talking
AT_USERNAME=sandbox                  # your AT username (sandbox for testing)
AT_API_KEY=your_at_api_key

サンドボックスの認証情報

Daraja アカウントを新規作成する場合や、新しいマシンでセットアップする場合は、サンドボックスのセットアップガイドに従ってください。このガイドには、検証済みの手順（Lipa Na M-Pesa Sandbox のみを選択してアプリを作成し、公開済みのテスト用ショートコードとパスキーを使用し、MPESA_CALLBACK_URL を監視可能なパブリック HTTPS アドレスに設定する方法）と、正常な結果の例が記載されています。コンシューマーキーは共有できないため、開発者はそれぞれ無料のサンドボックスアプリを作成してください。

M-Pesa サンドボックス： https://developer.safaricom.co.ke — 無料アプリを作成してテスト用認証情報を取得します。

• テスト用ショートコード：174379
• テスト用パスキー：bfb279f9aa9bdbcf158e97dd71a467cd2e0c893059b10f78e6b72ada1ed2c919

Africa's Talking サンドボックス： https://account.africastalking.com — username=sandbox と任意の API キーを使用します。

Claude Desktop での使用方法

（macOS の場合）~/Library/Application Support/Claude/claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "mpesa": {
      "command": "uvx",
      "args": ["mpesa-mcp"],
      "env": {
        "MPESA_CONSUMER_KEY": "your_key",
        "MPESA_CONSUMER_SECRET": "your_secret",
        "MPESA_SHORTCODE": "174379",
        "MPESA_PASSKEY": "your_passkey",
        "MPESA_CALLBACK_URL": "https://yourdomain.com/mpesa/callback",
        "MPESA_SANDBOX": "true",
        "AT_USERNAME": "sandbox",
        "AT_API_KEY": "your_at_key"
      }
    }
  }
}

Claude Code での使用方法

claude mcp add mpesa -- uvx mpesa-mcp

claude を実行する前に、シェルで環境変数を設定してください。

プロンプトの例

接続後、AI エージェントに次のように依頼できます。

「注文 #1234 のために、+254712345678 に KES 500 の STK Push を送信して」

「支払い QKL8ABC123 が受領済みか確認して」

「本日のトウモロコシ価格を、この 50 人の農家に SMS で送信して：[リスト]」

「現地エージェント用に KES 50 分のエアタイムをチャージして：[電話番号のリスト]」

実際の活用例

現地エージェントへの支払い

「本日のデータ収集のため、以下の 12 人の現地エージェントそれぞれに KES 300 の STK Push を送信して：[リスト]」

エージェントは 12 件の STK Push を順番に実行し、それぞれの checkout_request_id を追跡して確認をポーリングします。コードを書く必要はありません。

農家への警報とエアタイム

「ガリッサの農家 200 人に、川の水位が上昇していることを SMS で知らせて。その後、報告の電話をかけられるよう、それぞれに KES 20 分のエアタイムをチャージして」

1 つのプロンプトで、Safaricom、Airtel、Telkom を通じて SMS 200 件とエアタイムのチャージ 200 件を実行できます。

支払いの照合

「領収書 OKL8M3B2HF の支払いが成功したか、また金額はいくらだったか確認して」

Claude を利用するサポート担当者が、M-Pesa の取引をリアルタイムで確認する際に役立ちます。

ツールの注釈

すべてのツールはMCP ツールの注釈を宣言しているため、クライアントは適切に呼び出しを制御できます。

ツール	readOnly	destructive	idempotent
mpesa_stk_push	❌	✅	❌
mpesa_stk_query	✅	❌	✅
mpesa_transaction_status	✅	❌	✅
sms_send	❌	✅	❌
airtime_send	❌	✅	❌

Claude Desktop やその他の MCP クライアントは、決済、SMS、またはエアタイムの操作を実行する前に確認を求めます。

サーバーの検出

機能は.well-known/mcp.jsonを介して公開されます。これは新たに登場した MCP Server Cards 標準です。レジストリやブラウザーは、このサーバーに接続することなく、ツールをインデックス化できます。

# Check capabilities
curl https://raw.githubusercontent.com/gabrielmahia/mpesa-mcp/main/.well-known/mcp.json

テストと精度

これらのテストでは、このサーバーの動作を確認します。この README は、このサーバーを使用するモデルの精度について何も主張しません。

mpesa-mcp は、ケニアの電話番号の3種類すべての形式、金額の境界値、任意フィールドの欠落についてテストされています。

pytest tests/ -v  # run full suite
pytest tests/test_phone_formats.py  # format normalization
pytest tests/test_boundary_amounts.py  # min/max amount edge cases

書き込み操作（STK プッシュ、SMS、エアタイム）では、API 呼び出しの前に明示的な検証が行われます。

エコシステムの概要 — Mojaloop + MCP

Mojaloop（ゲイツ財団の資金提供による）は、東アフリカをはじめとする地域で、銀行、モバイルマネーのウォレット、加盟店を DFSP 間でつなぎ、決済の相互運用性を実現します。

mpesa-mcp は、AI エージェントのツール層を担い、AI コーディングアシスタントが M-Pesa の決済をプログラムから実行、照会できるようにします。

これらは互いに補完するものです。

• Mojaloop：金融サービスプロバイダー間をつなぐ相互運用性の基盤
• mpesa-mcp：AI エージェントをその基盤につなぐ MCP インターフェース層

このパターンの詳細については、Mojaloop のドキュメントへの貢献をご覧ください。

MCP と A2A — 2つの異なるプロトコル

mpesa-mcp は、AI エージェントがツールとやり取りする方法を定める MCP（Model Context Protocol）を実装しています。

これを補完するプロトコルとして、エージェント同士のやり取りを扱う A2A（Agent-to-Agent）があります。それぞれ異なる問題を解決し、連携して機能します。

• MCP：AI エージェント → mpesa-mcp → Daraja API / Africa's Talking
• A2A：オーケストレーターエージェント ↔ 決済サブエージェント ↔ 通知サブエージェント

ほとんどの統合では MCP だけで十分です。A2A は、決済ワークフローが他の専門エージェントと連携するマルチエージェントシステムを構築する場合に関係します。

---

開発

git clone https://github.com/gabrielmahia/mpesa-mcp
cd mpesa-mcp
pip install -e ".[dev]"
pytest tests/ -v

セキュリティ

API キーをコミットしないでください。環境変数またはシークレットマネージャーを使用してください。
脆弱性の報告先：[email protected]

研究の背景

スワヒリ語と翻訳（arXiv:2509.04516、2025年）：小規模なニュース分類実験では、スワヒリ語ネイティブの BERT モデルの誤り率は 0.36% で、機械翻訳したスワヒリ語に英語モデルを適用した場合の 1.47% を下回りました。このタスクでは、翻訳してから分類するよりもネイティブモデルのほうが優れていました。このサーバーのツールの説明は、英語だけでなくスワヒリ語でも読めるように書かれていますが、その効果はここでは測定されていません。

MCP のセキュリティ研究（arXiv:2603.18063、arXiv:2603.21642、2026年）：ツールの説明を介したプロンプトインジェクションは、MCP における主要な攻撃経路です。mpesa-mcp は、静的でバージョン管理されたツールの説明と厳格な入力検証によって、これを緩和しています。

関連インフラストラクチャ：

• wapimaji-mcp — ケニアの干ばつ対応 MCP（シミュレーションデータ）
• civic-agent-kit — ケニアの市民データ MCP
• swahili-health-mcp — ケニア DHS 2022 の郡別保健指標 MCP
• kenya-legal-rag — ケニアの法令コーパス MCP
• ポートフォリオ全体：gabrielmahia.github.io

ライセンス

MIT — © 2026 Gabriel Mahia

最新情報を受け取る

新しいリリースや東アフリカの API に関する最新情報を受け取れます： 更新情報を購読 →

または、GitHub でこのリポジトリをウォッチすると、リリース通知を受け取れます。

関連パッケージ

パッケージ	インストール	説明
wapimaji-mcp	pip install wapimaji-mcp	干ばつのフェーズと SMS アラートをシミュレートする MCP サーバー（実際の NDMA データはまだありません）
civic-agent-kit	pip install civic-agent-kit	東アフリカの市民向け AI SDK

関連パッケージ

すべて MIT ライセンス · すべて東アフリカの市民向け AI スタックの一部です

パッケージ	インストール	説明
wapimaji-mcp	pip install wapimaji-mcp	干ばつのフェーズと SMS アラートをシミュレートする MCP サーバー（実際の NDMA データはまだありません）
kenya-health-mcp	pip install kenya-health-mcp	ケニアの医療データ MCP — SHA／SHIF、施設、母子保健、権利
civic-agent-kit	pip install civic-agent-kit	東アフリカの市民向け AI SDK

ポートフォリオ全体：gabrielmahia.github.io

東アフリカ連携スタックの一部

この MCP サーバーはケニアの連携インフラの一部です。 africa-coord-bus に接続すると、 ドメイン間のシグナルを自動的にルーティングする連携イベントバスを利用できます。

pip install africa-coord-bus

すべてのサーバー：pypi.org/user/gmahia ライブデモ：coord-cascade-demo

知的財産とコラボレーション

MIT ライセンスです。フィードバックは GitHub Issues のみで受け付けており、プルリクエストは受け付けていません。デモデータには DEMO と表示されており、運用上の判断には適していません。ポリシー全文：docs/architecture/IP_POLICY.md。セキュリティに関する報告：SECURITY.md をご覧ください。

東アフリカ連携スタックの一部

• インストールして実行： pip install reli-cli && reli list — 公式 MCP Registry に io.github.gabrielmahia として登録されている MCP サーバー
• スワヒリ語のエージェントタスクであらゆるモデルを評価： kipimo · データセット · リーダーボード
• サーバー間を連携： africa-coord-bus — ケニアのルーティングテーブルを組み込んだ、オフライン優先のイベントバス
• データセット： huggingface.co/gmahia · ドキュメントハブ： nairobi-stack

設計上、特定のモデルに依存しません。クローズド API、オープンウェイトモデル、小型の蒸留モデルをすべて主要な選択肢として扱います。

送金ツールの安全制限（0.3.0、ライブモードでは破壊的変更）

言語モデルは、誰にでも任意の金額を支払うよう説得される可能性があります。決済ツールに対するプロンプトインジェクションは、エージェント決済プロトコル（AP2、x402）で確認されている攻撃です。そのため、ライブモード（MPESA_SANDBOX=false）では、8つの出金ツール（mpesa_b2c、mpesa_business_paybill、mpesa_business_buygoods、mpesa_business_pochi、mpesa_reversal、mpesa_tax_remittance、mpesa_b2b_express_checkout、airtime_send）に次の制限が適用されます。

• 確認： confirm_send=true を指定して呼び出さない限り、実行を拒否します。エージェントは受取人と金額をユーザーに示し、明示的な承認を得た後にのみ、この値を設定する必要があります。
• 上限： MPESA_MAX_AMOUNT_KES（デフォルトは 20,000、0 = 上限なし）を超える金額は拒否されます。
• セッション予算： 1つのサーバープロセスが承認できる合計金額は、MPESA_SESSION_BUDGET_KES（デフォルトは 50,000、0 = 予算なし）までです。上限は1件の支払い額を制限し、予算は合計額を制限するため、エージェントが上限内の支払いを無制限に繰り返すことはできません。支払いが承認された時点で計上され、その後の呼び出しが失敗しても返金されません（タイムアウトした呼び出しでも、送金が実行されている可能性があります）。サーバーを再起動した場合にのみリセットされます。変更できるのはオペレーターだけで、モデルは変更できません。1回のセッションで正当な理由により300,000 KESを超える送金を行う場合は、値を引き上げてください。
• モデルではなく本人が確認します（0.5.0）： ライブモードでは、8つの出金ツールについて、処理の実行前に、サーバーがMCPクライアントを通じてあなたに正確な支払い内容（受取人の正式名称、金額、参照情報）の承認を求めます。どちらのプロトコル世代でもMCPエリシテーションを使用します。モデルがあなたの代わりに回答することはできません。モデルが confirm_send=true と指定しても、あなたは拒否できます。承認はその正確な呼び出しに紐付き（異なる金額や受取人には新たな承認が必要）、1回のみ有効で、5分後に期限切れになります。上限超過、予算超過、許可リスト未登録など、サーバーがいずれにせよ拒否する支払いについて、あなたに確認が求められることはありません。MPESA_CONFIRM_MODE の設定値は、auto（デフォルト：クライアントが回答可能な場合は確認を求め、そうでなければ confirm_send パラメーターにフォールバック）、elicit（厳格モード：クライアントがプロンプトを表示できない場合は拒否）、param（従来の動作）です。サンドボックスでは確認を求めません。まだエリシテーションに対応していないクライアントもあります。お使いのクライアントが対応していない場合は、フォールバックするのではなく拒否するよう elicit モードを使用し、クライアント独自の呼び出しごとの承認も有効にしておいてください。
• 許可された受取人： MPESA_ALLOWED_RECIPIENTS（電話番号、Paybill、Tillをカンマ区切りで指定）を設定すると、出金ツールはその受取人にのみ支払い、その他はすべて拒否されます。電話番号はケニア国内のどの形式でも照合されます。未設定の場合は制限なしです。本番環境では、支払い先を限定することが推奨されます。支払い可能な相手を限定するという考え方は、加盟店を限定した決済トークンや、特定加盟店向けの予約と同じです。ReversalとTax remittanceには自由に指定できる受取人がないため、このリストは適用されません。
• セッションレポート： 読み取り専用の mpesa_session_report ツールは、サーバー独自の記録に基づき、制限、使用済み額と残額、受取人をマスキングした直近10件の承認または拒否を返します。支払い前に予算を確認し、モデルの申告に頼らず、サーバーが実際に何を承認したか検証するために使用してください。

ツールの外側でも損失を限定する

これらのガードは、エージェントが制御するレイヤーであるツールの内部で動作します。その外側には2つのチェックがあり、両方を使い、上限を低く設定してください。

1. confirm_send はモデル自身が指定するものなので、これだけでは独立したチェックになりません。0.5.0 以降、サーバーはクライアントを通じて直接確認を求めます（上記を参照）。クライアントにそのプロンプトを表示できない場合は、8つの送金ツールについて、MCP クライアント独自の呼び出しごとの承認を有効にし、「常に許可」に設定しないでください。
2. 決済手段側でも損失を限定してください。 失ってもよい金額だけを入れた専用のビジネス用ショートコードまたは業務用口座から支払い、M-PESA 組織アカウントで利用できる実行者の上限や承認（メーカー・チェッカー）制御を使ってください。このサーバーからはそれらを確認できないため、Safaricom の最新のドキュメントを確認してください。

これは、インドのエージェント型決済の実証実験（事前入金された加盟店限定の予約枠と、ネットワークが適用する委任上限）と Alipay のエージェント決済（エージェントが支払えるユーザー設定のしきい値と、それを超えた場合の人による確認、エージェントの権限を確認・取り消す方法、そして損失保証）で、それぞれ独自に採用された多層設計です。

3. 少額から始めてください。 ここでのデフォルト値（1回の支払いあたり20,000 KES、1セッションあたり50,000。0.5.0 では100,000と300,000から引き下げ）は推奨額ではなく上限です。AI アシスタントを介した音声またはテキストでの支払いを顧客に許可するブラジルの銀行では、1回あたりおよそR$200～R$800から開始し、支払いごとに確認を求め、それより高額な支払いは銀行独自のアプリに誘導しています。これは、ここでのデフォルト値と同程度です。MPESA_MAX_AMOUNT_KES と MPESA_SESSION_BUDGET_KES は実際に必要な最小限の金額に設定し、理由がある場合に限って引き上げてください。

• オプトアウト： MPESA_REQUIRE_CONFIRMATION=false にすると、管理下の完全自動化セットアップでは確認が不要になります。明確な意図がある場合に限り、そうしてください。
• サンドボックスには制限がありません。 顧客承認が必要なフロー（STK Push、Ratiba、Bill Manager）に変更はありません。顧客は自身の端末で承認します。