MCP Flutterwave

mcp-flutterwave

An MCP (Model Context Protocol) server that enables AI assistants to interact with the Flutterwave API — create payment links, charge customers directly, manage transfers, collect via virtual accounts, pay bills, and more.

Note: This server currently targets the Flutterwave v3 API. Support for v4 is coming soon.

Also ships with a built-in web app that connects to the MCP server and lets you talk to a Claude-powered Flutterwave assistant directly in your browser.

---

Contents

• Features
• Installation
• Available Tools
• Card Charge Flow
• Virtual Accounts
• Bill Payment Flow
• FX Trade Flow
• Verification
• Stablecoins
• Web App
• MCP Server Setup
• Usage with Claude Desktop
• MCP-UI Components
• Contributing
• Changelog
• Security
• License

---

Features

• Checkout — Create hosted payment links and disable them
• Direct Charges — Charge customers via card, bank account, mobile money, M-Pesa, or USSD
• Full card auth flow — PIN, AVS (Address Verification), 3D Secure redirect, and OTP validation all handled automatically
• Charge Validation — Validate OTP-based charges with a dedicated tool
• Transactions — Verify by ID or reference, view event timeline, resend failed webhooks
• Transfers — Initiate single transfers, manage beneficiaries
• Payment Plans — Create and retrieve subscription plans
• Virtual Accounts — Generate dedicated account numbers for NGN and GHS bank transfer collection (static or dynamic)
• Bill Payments — Pay airtime, data, cable TV, electricity, internet bills and more (Nigeria)
• FX Trade — Convert between NGN, GHS, and USD with live quotes (RFQ → trade in two steps)
• Verification — BVN identity verification, bank account name resolution, and card BIN lookup
• Stablecoins — Send USDC/USDT to Polygon wallets, or convert NGN/USD fiat into stablecoins
• Rich UI — Every tool returns a branded HTML card rendered inline in supported clients
• Web App — A standalone browser chat interface powered by Claude + this MCP server

---

Installation

npm

npm install -g mcp-flutterwave

npx (no install needed)

npx mcp-flutterwave --tools=all

Docker

Pull the image:

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

The server communicates over stdio, so it must be launched by an MCP client — not run standalone. Configure Claude Desktop to use the Docker image as the MCP server:

{

"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" ] } } }

The -i flag keeps stdin open so Claude Desktop can communicate with the server over stdio.

Requirements: Node.js 20 or later (for npm/npx).

---

Available Tools

Checkout

Direct Charges

Transactions

Transfers

Payment Plans

Virtual Accounts

Bill Payments

FX Trade

Verification

Stablecoins

---

Card Charge Flow

Direct card charges are multi-step. The charge_card tool handles every stage automatically and tells Claude what to do next.

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

Authorization parameters

When a second call is needed, pass authorization alongside the original card details:

// 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 cards

American Express transactions require the card_holder_name field in addition to standard card details.

Payload encryption

Card payloads are encrypted with 3DES-ECB using your FLW_ENCRYPTION_KEY before they are sent to Flutterwave (PCI DSS requirement). The encryption is handled automatically — set the environment variable and the server does the rest.

---

Virtual Accounts

Virtual accounts give each customer a dedicated bank account number to make transfers into. Flutterwave notifies your webhook when a payment arrives.

NGN static account

{

"email": "customer@example.com", "currency": "NGN", "tx_ref": "VA-NGN-001", "is_permanent": true, "bvn": "22415929481" }

GHS dynamic account

{

"email": "customer@example.com", "currency": "GHS", "tx_ref": "VA-GHS-001", "amount": 500, "frequency": 5, "duration": 7 }

After creation, save the order_ref — it is the key for retrieving or updating the account via get_virtual_account and update_virtual_account.

---

Bill Payment Flow

Bill payments follow a 6-step discovery flow. Skip validate_bill_customer for airtime and mobile data.

1. get_bill_categories

↓ choose a category (e.g. UTILITYBILLS)

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

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

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

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

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

Supported categories

Bill payments are available for Nigeria only (country: NG).

---

FX Trade Flow

Currency conversion uses a two-step quote-then-trade flow. Quotes are valid for 5 minutes and available weekdays only (Monday–Friday).

1. request_fx_quote(base_currency, target_currency, quantity)

↓ returns quote_id, status: NEW

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

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

1. get_