mcp-flutterwave

mcp-flutterwave

AI アシスタントが Flutterwave API を操作できるようにする MCP（Model Context Protocol） サーバーです。決済リンクの作成、顧客への直接請求、送金管理、バーチャル口座による集金、請求書の支払いなどに対応します。

注： 現在、このサーバーは Flutterwave v3 API を対象としています。v4 は近日対応予定です。

さらに、MCP サーバーに接続し、Claude を活用した Flutterwave アシスタントとブラウザー上で直接会話できる組み込みウェブアプリも付属しています。

---

目次

• 機能
• インストール
• 利用可能なツール
• カード請求のフロー
• バーチャル口座
• 請求書支払いのフロー
• FX 取引のフロー
• 本人確認
• ステーブルコイン
• ウェブアプリ
• MCP サーバーのセットアップ
• Claude Desktop での使用
• MCP-UI コンポーネント
• コントリビューション
• 変更履歴
• セキュリティ
• ライセンス

---

機能

• チェックアウト — ホスト型決済リンクの作成と無効化
• 直接請求 — カード、銀行口座、モバイルマネー、M-Pesa、または USSD で顧客に請求
• カード認証フロー全体 — PIN、AVS（住所確認）、3D セキュアリダイレクト、OTP 検証をすべて自動処理
• 請求の検証 — 専用ツールで OTP ベースの請求を検証
• 取引 — ID または参照情報での照合、イベントのタイムライン表示、失敗した Webhook の再送
• 送金 — 単一送金の開始、受取人の管理
• 支払いプラン — サブスクリプションプランの作成と取得
• バーチャル口座 — NGN および GHS の銀行振込による入金用に専用口座番号を生成（静的または動的）
• 請求書の支払い — 通話時間、データ、ケーブルテレビ、電気、インターネットなどの料金を支払い（ナイジェリア）
• FX 取引 — ライブ見積もりを使って NGN、GHS、USD 間で通貨を交換（RFQ → 2 ステップで取引）
• 本人確認 — BVN による本人確認、銀行口座名義の照会、カード BIN の検索
• ステーブルコイン — USDC/USDT を Polygon ウォレットに送金、または NGN/USD の法定通貨をステーブルコインに交換
• リッチ UI — すべてのツールがブランド仕様の HTML カードを返し、対応クライアント内にインライン表示
• ウェブアプリ — Claude とこの MCP サーバーを利用する、独立したブラウザーチャットインターフェース

---

インストール

npm

npm install -g mcp-flutterwave

npx（インストール不要）

npx mcp-flutterwave --tools=all

Docker

イメージを取得します。

docker pull ghcr.io/bajoski34/mcp-flutterwave:latest

サーバーは stdio で通信するため、単独で実行するのではなく、MCP クライアントから起動する必要があります。Docker イメージを MCP サーバーとして使うよう Claude Desktop を設定します。

{
  "mcpServers": {
    "flutterwave": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "FLW_SECRET_KEY=YOUR_SECRET_KEY",
        "-e", "FLW_ENCRYPTION_KEY=YOUR_ENCRYPTION_KEY",
        "ghcr.io/bajoski34/mcp-flutterwave:latest"
      ]
    }
  }
}

-i フラグを指定すると stdin が開いたままになり、Claude Desktop が stdio 経由でサーバーと通信できます。

要件： Node.js 20 以降（npm/npx を使用する場合）。

---

利用可能なツール

チェックアウト

ツール	説明
create_checkout	ホスト型 Flutterwave 決済リンクを作成
disable_checkout	既存の決済リンクを無効化

直接課金

ツール	説明
charge_card	デビットカードまたはクレジットカードに直接課金します。PIN、AVS、3DS、OTP のフローに対応しています
charge_bank_account	銀行口座から引き落とします（NGN／GHS）
charge_mobile_money	モバイルマネー（ガーナ、ウガンダ、ルワンダ、ザンビア、フランス語圏アフリカ）
charge_mpesa	M-Pesa で課金します（KES）
charge_ussd	USSD で課金します（NGN）
validate_charge	OTP を使用して保留中の課金を検証します

取引

ツール	説明
read_transaction	ID で取引の詳細を取得します
read_transaction_with_reference	tx_ref で取引の詳細を取得します
read_transaction_timeline	取引のイベントタイムラインを表示します
resend_transaction_webhook	失敗した Webhook を再送信します

送金

ツール	説明
create_transfer	銀行振込を開始します
create_beneficiary	新しい送金先を保存します
list_beneficiaries	保存済みの送金先をすべて一覧表示します

支払いプラン

ツール	説明
create_payment_plan	定期支払いプランを作成します
get_payment_plans	オプションのフィルターを指定して、支払いプランを一覧表示します

仮想口座

ツール	説明
create_virtual_account	顧客専用の銀行口座番号を作成します（NGN または GHS）
get_virtual_account	order_ref で仮想口座のステータスと詳細を取得します
update_virtual_account	NGN 仮想口座に BVN を紐付けるか、更新します
list_virtual_account_bulk	一括処理で作成されたすべての口座を一覧表示します

請求書の支払い

ツール	説明
get_bill_categories	利用可能な請求カテゴリを一覧表示します（AIRTIME、CABLEBILLS、UTILITYBILLS など）
get_bill_providers	カテゴリの請求事業者／プロバイダーを一覧表示します
get_bill_items	特定の請求事業者の支払い可能な項目を一覧表示します
validate_bill_customer	支払い前に顧客アカウントを検証します（メーター番号、スマートカードなど）
pay_bill	請求書の支払いを送信します
get_bill_status	支払いステータスを確認し、プリペイドトークンを取得します（電気）

FX 取引

ツール	説明
request_fx_quote	通貨換算の見積依頼（RFQ）を送信します
get_fx_quote	見積のステータスをポーリングします。取引を行う前に READY になるまで待ちます
initiate_fx_trade	READY 状態の見積を確定し、取引を実行します
get_fx_trade	SETTLED または FAILED になるまで取引ステータスをポーリングします

検証

ツール	説明
initiate_bvn_verification	BVN による本人確認を開始します。顧客の一度限りの同意 URL を返します
get_bvn_details	同意取得後に BVN の本人確認データ全件を取得します
resolve_bank_account	銀行口座番号から口座名義を照会します
verify_card_bin	カード番号の最初の 6 桁からカードブランド、種類、発行会社、国を照会します

ステーブルコイン

ツール	説明
get_stablecoin_fee	送金前に手数料を取得します。受取人が受け取る正味金額を表示します
send_stablecoin	Polygon ウォレットアドレスに USDC または USDT を送金します
convert_to_stablecoin	NGN または USD の法定通貨残高を USDC または USDT に換算します

---

カード課金フロー

カードへの直接課金は複数のステップで構成されます。charge_card ツールが各段階を自動的に処理し、次に何をすべきかを Claude に伝えます。

1. charge_card(card details)
        │
        ├─ mode: "pin"        → ask customer for PIN
        │       charge_card(same params + authorization: { mode: "pin", pin: "..." })
        │               │
        │               ├─ mode: "otp"      → validate_charge(flw_ref, otp)
        │               └─ mode: "redirect" → send customer to 3DS URL
        │
        ├─ mode: "avs_noauth" → ask customer for billing address
        │       charge_card(same params + authorization: { mode: "avs_noauth", city, address, ... })
        │               │
        │               ├─ mode: "otp"      → validate_charge(flw_ref, otp)
        │               └─ mode: "redirect" → send customer to 3DS URL
        │
        ├─ mode: "redirect"   → send customer to 3DS URL, then read_transaction to verify
        │
        └─ (none)             → charge complete — read_transaction to verify

認証パラメーター

2 回目の呼び出しが必要な場合は、元のカード情報とともに authorization を渡します。

// PIN flow
{ "authorization": { "mode": "pin", "pin": "3310" } }

// AVS flow
{ "authorization": { "mode": "avs_noauth", "city": "Lagos", "address": "12 Victoria Island", "state": "LA", "country": "NG", "zipcode": "100001" } }

AMEX カード

American Express の取引では、標準的なカード情報に加えて card_holder_name フィールドが必要です。

ペイロードの暗号化

Flutterwave に送信する前に、カードのペイロードは FLW_ENCRYPTION_KEY を使用して 3DES-ECB で暗号化されます（PCI DSS の要件）。暗号化は自動的に処理されます。環境変数を設定すれば、サーバーが残りの処理を行います。

---

仮想口座

仮想口座を使うと、各顧客に専用の銀行口座番号を割り当て、そこへ送金してもらえます。入金があると、Flutterwave から Webhook に通知が届きます。

機能	NGN	GHS
動的（1回限り）	✓ — amount を設定。有効期限は約1時間です	✓ — frequency と duration を使用します
静的（再利用可能）	✓ — is_permanent: true、BVN が必要です	✓ — is_permanent: true
BVN が必要	静的口座のみ	不要

NGN 静的口座

{
  "email": "[email protected]",
  "currency": "NGN",
  "tx_ref": "VA-NGN-001",
  "is_permanent": true,
  "bvn": "22415929481"
}

GHS 動的口座

{
  "email": "[email protected]",
  "currency": "GHS",
  "tx_ref": "VA-GHS-001",
  "amount": 500,
  "frequency": 5,
  "duration": 7
}

作成後は order_ref を保存してください。これは、get_virtual_account と update_virtual_account を使って口座を取得または更新するためのキーです。

---

請求書支払いのフロー

請求書の支払いは、6ステップの検索フローに従います。エアタイムとモバイルデータの場合は validate_bill_customer を省略してください。

1. get_bill_categories
        ↓ choose a category (e.g. UTILITYBILLS)

2. get_bill_providers(category)
        ↓ get biller_code (e.g. "BIL127" for IKEDC)

3. get_bill_items(biller_code)
        ↓ get item_code and amount info

4. validate_bill_customer(item_code, customer_id)   ← skip for AIRTIME / MOBILEDATA
        ↓ confirm customer name and details

5. pay_bill(biller_code, item_code, customer_id, amount)
        ↓ returns reference

6. get_bill_status(reference)
        ↓ confirms completion
          for electricity: prepaid token is in extra.token — share it with the customer

対応カテゴリ

コード	説明
AIRTIME	モバイルエアタイムのチャージ
MOBILEDATA	データバンドルの購入
CABLEBILLS	ケーブルテレビ（DSTV、GOTV、StarTimes）
INTSERVICE	インターネットサービスのサブスクリプション
UTILITYBILLS	電気料金（プリペイドおよびポストペイド）
TAX	政府への税金の支払い
DONATIONS	慈善団体への寄付
TRANSLOG	輸送／物流
DEALPAY	取引の支払い
RELINST	宗教施設
SCHPB	学校／教育費の支払い

請求書の支払いはナイジェリアのみで利用できます（country: NG）。

---

FX 取引のフロー

通貨換算は、見積もりを取得してから取引する2段階のフローで行います。見積もりの有効期間は5分間で、平日のみ（月曜日から金曜日）利用できます。

1. request_fx_quote(base_currency, target_currency, quantity)
        ↓ returns quote_id, status: NEW

2. get_fx_quote(quote_id)   ← poll until READY or FAILED
        ↓ READY: contains rate, approved_quantity, total_value, expiry

3. initiate_fx_trade(quote_id, narration)
        ↓ locks in rate, returns trade_id, status: NEW

4. get_fx_trade(trade_id)   ← poll until SETTLED or FAILED
        ↓ SETTLED: converted funds credited to target currency wallet instantly

対応通貨ペア

ペア	売却	受取
NGN/USD	ナイジェリア・ナイラ	米ドル
GHS/USD	ガーナ・セディ	米ドル
USD/NGN	米ドル	ナイジェリア・ナイラ

見積もりのステータス

ステータス	意味
NEW	見積もりを算出中です
READY	レートが確定しています — ただちに initiate_fx_trade を呼び出してください
PROCESSING	この見積もりで取引が開始されています
EXPIRED	5分間の有効期間が過ぎました — 新しい見積もりを送信してください
FAILED	対応していないペア、最低金額未満、または口座の上限超過です

取引のステータス

ステータス	意味
NEW	取引がキューに登録されています
PENDING	実行中です
SETTLED	資金が交換され、対象通貨のウォレットに入金されています
FAILED	残高不足または処理エラーです

主な制約

• 最低取引額： 基準通貨で1,000米ドル相当
• 見積もりの有効期間： 発行から5分間（READY 状態）
• 1回限りの使用： 各見積もりは1回の取引にのみ使用できます
• 承認数量： 流動性や口座の上限により、リクエストした数量と異なる場合があります — 照合には必ず approved_quantity を使用してください
• 口座の有効化： 口座で FX 取引を有効にするには、[email protected] にお問い合わせください

---

検証

銀行口座の照会

送金前に、受取人の口座情報を確認してください。送金を進める前に、照会された名義を必ずユーザーに表示してください。

{ "account_number": "0690000040", "account_bank": "044" }

主な銀行コード：044 Access Bank · 057 Zenith Bank · 058 GTBank · 033 UBA · 011 First Bank

カード BIN の照会

カード番号の最初の6桁からカードのメタデータを特定します。

{ "bin": "553188" }
// → { brand: "MASTERCARD", type: "CREDIT", issuer: "NEXUS MERCHANT BANK", country: "NIGERIA" }

BIN によって AMEX カードと特定された場合、charge_card の呼び出し時に card_holder_name フィールドが必要です。

BVN の検証（ナイジェリア）

2段階の同意フローです。顧客は NIBSS ポータルでデータ共有を承認する必要があります。

1. initiate_bvn_verification(bvn, firstname, lastname, redirect_url)
        ↓ returns reference + single-use consent URL

2. Customer visits consent URL → approves data sharing on NIBSS portal
        ↓ webhook (bvn.completed) fires OR poll:

3. get_bvn_details(reference)
        ↓ returns name, DOB, gender, phone, NIN, state of origin, watchlist status

Flutterwave 口座の有効化が必要です。[email protected] にお問い合わせください。顧客がすでに同意している場合、initiate_bvn_verification は url: null を返すため、すぐに get_bvn_details を呼び出せます。

---

ステーブルコイン

Polygon ネットワーク経由で USDC または USDT を送金するか、NGN／USD の法定通貨残高をステーブルコインに換算します。受取人が受け取る正味額をユーザーに知らせるため、必ず最初に get_stablecoin_fee を呼び出してください。

ウォレット間の送金

1. get_stablecoin_fee(amount, currency: "USDT", debit_currency: "USDT")
        ↓ shows fee and net amount

2. send_stablecoin(wallet_address, amount, currency, debit_currency)
        ↓ returns reference and transfer status

法定通貨からステーブルコインへの換算

1. get_stablecoin_fee(amount, currency: "USDC", debit_currency: "NGN")
        ↓ shows fee (percentage-based) and net USDC amount

2. convert_to_stablecoin(merchant_id, amount, currency, debit_currency: "NGN")
        ↓ deducts NGN from your fiat wallet, credits USDC/USDT

主な制約

制約	詳細
ネットワーク	Polygon のみ — Tron、Solana、Stellar は対象外です
通貨	USDC と USDT
ウォレット形式	EVM アドレス：0x + 40 桁の 16 進数（合計 42 文字）
法定通貨のソース	convert_to_stablecoin では NGN または USD、send_stablecoin ではステーブルコインが currency と一致する必要があります
手数料の種類	同一通貨の場合は固定手数料、法定通貨からステーブルコインへの変換では割合手数料

---

Web アプリ

app/ ディレクトリには、この MCP サーバーを Claude 搭載の会話ループで利用する、独立したブラウザーチャットインターフェースが含まれています。

仕組み

Browser  →  POST /api/chat
               ↓
           Claude (Sonnet) — all MCP tools injected via advanced-tool-use beta
               ↓  tool_use
           MCP Server (this repo, spawned via stdio)
               ↓
           Flutterwave API

Web アプリでは、Anthropic Advanced Tool Use の次の 3 つの機能を使用します。

• Tool Search — コア以外のツールは遅延読み込みされ、必要に応じてロードされるため、トークン使用量を約 85% 削減できます
• Programmatic Tool Calling — Claude は、会話コンテキストを膨らませることなく、複数のツールを順番に呼び出すコードを記述できます
• Tool Use Examples — 各ツールの厳選された input_examples により、パラメーターの精度が約 72% から約 90% に向上します

アプリは、ツールの応答ごとに、チェックアウトリンク、取引の詳細、請求状態、送金の概要、バーチャル口座、請求書の領収書などを表示する、ブランドに合わせたリッチな UI カードを返します。これらはチャット内にインラインでレンダリングされます。

Web アプリの実行

前提条件

変数	必須	説明
FLW_SECRET_KEY	はい	Flutterwave のシークレットキー
FLW_ENCRYPTION_KEY	カード決済の場合	Flutterwave の暗号化キー
ANTHROPIC_API_KEY	はい	Anthropic の API キー

Flutterwave Dashboard の Settings → API Keys からキーを取得してください。
Anthropic のキーは Anthropic Console から取得してください。

ビルドと起動

# Clone and install
git clone https://github.com/bajoski34/mcp-flutterwave.git
cd mcp-flutterwave
npm install

# Build both the MCP server and the web app
npm run build:all

# Start
ANTHROPIC_API_KEY=sk-ant-... FLW_SECRET_KEY=FLWSECK_... npm run start:app

次に、http://localhost:3000 を開きます。

利用可能なスクリプト

スクリプト	説明
npm run build	MCP サーバーのみをビルドします
npm run build:app	Web アプリのみをビルドします
npm run build:all	すべてをビルドします
npm run start:app	Web アプリを起動します（事前にビルドが必要です）
npm run dev:app	すべてをビルドしてから Web アプリを起動します
npm test	テストスイートを実行します

ポート

デフォルトの 3000 から変更するには、PORT 環境変数を設定します。

---

MCP サーバーのセットアップ

npm 経由

npm install -g mcp-flutterwave

GitHub 経由

git clone https://github.com/bajoski34/mcp-flutterwave.git
cd mcp-flutterwave
npm install
npm run build

環境変数

変数	必須	説明
FLW_SECRET_KEY	はい	Flutterwave のシークレットキー
FLW_ENCRYPTION_KEY	カード決済の場合	Flutterwave の暗号化キー（Dashboard → Settings → API から取得）

---

Claude Desktop での使用

以下を claude_desktop_config.json に追加します。詳細は MCP クイックスタートを参照してください。

すべてのツールを有効にするには --tools=all を渡します。登録するツールを制限するには、カンマ区切りのリストを指定します。

npm 経由

{
  "mcpServers": {
    "flutterwave": {
      "command": "mcp-flutterwave",
      "args": ["--tools=all"],
      "env": {
        "FLW_SECRET_KEY": "YOUR_SECRET_KEY",
        "FLW_ENCRYPTION_KEY": "YOUR_ENCRYPTION_KEY"
      }
    }
  }
}

ローカルビルド経由

{
  "mcpServers": {
    "flutterwave": {
      "command": "node",
      "args": [
        "/path/to/mcp-flutterwave/build/index.js",
        "--tools=all"
      ],
      "env": {
        "FLW_SECRET_KEY": "YOUR_SECRET_KEY",
        "FLW_ENCRYPTION_KEY": "YOUR_ENCRYPTION_KEY"
      }
    }
  }
}

ツールの選択

"args": [
  "--tools=create_checkout,read_transaction,create_transfer"
]

指定可能なツール名（すべてを有効にするには all を使用します）：

create_checkout            disable_checkout
read_transaction           read_transaction_with_reference
read_transaction_timeline  resend_transaction_webhook
create_transfer            create_beneficiary            list_beneficiaries
create_payment_plan        get_payment_plans
charge_card                charge_bank_account           charge_mobile_money
charge_mpesa               charge_ussd                   validate_charge
create_virtual_account     get_virtual_account           update_virtual_account
list_virtual_account_bulk
get_bill_categories        get_bill_providers            get_bill_items
validate_bill_customer     pay_bill                      get_bill_status
request_fx_quote           get_fx_quote
initiate_fx_trade          get_fx_trade
initiate_bvn_verification  get_bvn_details
resolve_bank_account       verify_card_bin
get_stablecoin_fee         send_stablecoin               convert_to_stablecoin

---

MCP-UI コンポーネント

すべてのツールは、テキスト応答に加えて、@mcp-ui/server を利用したリッチな HTML カードを返します。カードには、Flutterwave のデザイントークンであるネイビー #0A0E27、ディープオレンジ #FF5804、ブランドオレンジ #F5A623 と、システムのサンセリフ書体が使用されています。

カード決済 UI の状態

状態	表示されるカード
PIN が必要	手順ごとの説明、取引リファレンス
AVS が必要	チップ形式で表示される必須の請求先住所フィールド
3DS リダイレクト	直接リンク付きの銀行認証 URL
OTP が必要	銀行からのメッセージ、validate_charge に渡す flw_ref
完了	金額、ステータスバッジ、取引リファレンスと Flutterwave リファレンス

バーチャルアカウント UI

バーチャルアカウントカードには、銀行口座番号が大きく目立つボックスで表示され、銀行名、口座の種類（Static / Dynamic）、通貨、有効期限、注文参照番号も併せて表示されます。

請求書支払い UI

ツール	表示されるカード
pay_bill	請求書のレシート — 請求先、項目、顧客 ID、金額、ステータス
get_bill_status	プリペイドトークン（電気）のステータスカード。大きな等幅フォントで表示し、共有に関する注記を添えます

認証 UI

ツール	表示されるカード
initiate_bvn_verification	同意カード — 顧客名（BVN は末尾 4 桁のみ表示）、1 回限りの同意リンクと開くボタン、手順ごとの説明
get_bvn_details	本人確認カード — 氏名、生年月日、性別、電話番号、NIN、出身州。BVN は一部をマスクし、該当する場合は赤いウォッチリストバッジを表示
resolve_bank_account	緑色の認証済みカード — 口座名義を大きく表示し、口座番号と銀行コードを併記
verify_card_bin	ブランドカラーのカード（Visa は青／Mastercard は赤／Amex は青／その他はダーク）— ブランド、種類バッジ、発行会社、国

ステーブルコイン UI

ツール	表示されるカード
get_stablecoin_fee	青を基調とした手数料カード — コインのペア、定額料金または割合の内訳、受取人の受取額
send_stablecoin	送金カード — 短縮表示されたウォレットアドレス、金額、ステータスバッジ
convert_to_stablecoin	変換カード — 法定通貨の引き落とし通貨、変換先のステーブルコイン、加盟店 ID、ステータス

FX 取引 UI

request_fx_quote/get_fx_quote と initiate_fx_trade/get_fx_trade は、いずれも濃紺を基調としたカードを返します。

状態	表示されるカード
Quote NEW / PROCESSING	銘柄バッジ、ステータスピル、ポーリングの案内
Quote READY	為替レート、承認済み数量、受取額、有効期限、アクションボタン
Quote FAILED / EXPIRED	理由付きのエラーメッセージ
Trade NEW / PENDING	目標通貨での金額、ポーリングの案内
Trade SETTLED	緑色の決済済みバナー、目標通貨での金額、受取人、ウォレットへの入金に関する注記
Trade FAILED	response_message を含む赤色の失敗バナー

カードは次に対応しています。

• Flutterwave Web App（このリポジトリの app/）— チャット内にインラインで表示
• MCP Inspector — 開発中のテストに使用
• HTML を含む resource コンテンツタイプに対応した任意の MCP クライアント

---

コントリビューション

コントリビューションを歓迎します。開始方法、開発ガイドライン、プルリクエストの提出方法については、コントリビューションガイドをお読みください。

---

変更履歴

重要な変更はすべて GitHub Releases に記載されています。

---

セキュリティ

セキュリティ上の脆弱性を発見した場合は、公開の issue を作成しないでください。代わりに、[email protected] まで直接メールでご連絡ください。できる限り速やかに対応いたします。

---

ライセンス

MIT © Abraham Olaobaju

全文については、LICENSE をご覧ください。