mcp-flutterwave

mcp-flutterwave

一个 MCP（Model Context Protocol） 服务，可让 AI 助手与 Flutterwave API 交互——创建支付链接、直接向客户收费、管理转账、通过虚拟账户收款、支付账单等。

**注意：**此服务目前面向 Flutterwave v3 API。即将支持 v4。

此外还内置了一个网页应用，可连接 MCP 服务，让你直接在浏览器中与由 Claude 驱动的 Flutterwave 助手对话。

---

目录

• 功能
• 安装
• 可用工具
• 银行卡收费流程
• 虚拟账户
• 账单支付流程
• 外汇交易流程
• 验证
• 稳定币
• 网页应用
• MCP 服务设置
• 与 Claude Desktop 配合使用
• MCP-UI 组件
• 贡献
• 更新日志
• 安全
• 许可证

---

功能

• 结账 — 创建托管式支付链接并将其停用
• 直接收费 — 通过银行卡、银行账户、移动支付、M-Pesa 或 USSD 向客户收费
• 完整的银行卡授权流程 — 自动处理 PIN、AVS（地址验证）、3D Secure 重定向和 OTP 验证
• 收费验证 — 使用专用工具验证基于 OTP 的收费
• 交易 — 按 ID 或引用编号验证交易、查看事件时间线、重新发送失败的 Webhook
• 转账 — 发起单笔转账、管理受益人
• 支付计划 — 创建和检索订阅计划
• 虚拟账户 — 为 NGN 和 GHS 生成专用账号，以便通过银行转账收款（静态或动态）
• 账单支付 — 支付话费、流量、有线电视、电费、网费等（尼日利亚）
• 外汇交易 — 使用实时报价在 NGN、GHS 和 USD 之间兑换（分两步：询价 → 交易）
• 验证 — BVN 身份验证、银行账户户名查询和银行卡 BIN 查询
• 稳定币 — 向 Polygon 钱包发送 USDC/USDT，或将 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 客户端启动，不能单独运行。配置 Claude Desktop，将 Docker 镜像用作 MCP 服务：

{
  "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	检查付款状态并获取预付费令牌（电费）

外汇交易

工具	描述
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

授权参数

需要再次调用时，请在原始卡片详情旁传入 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
动态（一次性）	✓ — 设置 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）。

---

外汇交易流程

货币兑换采用先报价、后交易的两步流程。报价有效期为 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 美元
• 报价有效期： 自发出报价（READY 状态）起 5 分钟
• 仅限使用一次： 每个报价只能用于一笔交易
• 批准数量： 可能因流动性或账户限额而异于请求数量——对账时请始终使用 approved_quantity
• 账户启用： 请联系 [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 验证（尼日利亚）

两步授权流程——客户必须在 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 个十六进制字符（共 42 个）
法币来源	convert_to_stablecoin 使用 NGN 或 USD；send_stablecoin 的稳定币必须与 currency 匹配
费用类型	同币种交易收取固定费用；法币 → 稳定币交易收取百分比费用

---

Web 应用

app/ 目录包含一个独立的浏览器聊天界面，通过 Claude 驱动的对话循环封装此 MCP 服务。

工作原理

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 功能：

• 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 Console 中获取 Anthropic 密钥。

构建并启动

# 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	运行测试套件

端口

设置 PORT 环境变量可将默认端口 3000 更改为其他端口。

---

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 组件

每个工具都会在文本响应之外返回一张丰富的 HTML 卡片，由 @mcp-ui/server 提供支持。卡片采用 Flutterwave 的设计令牌：藏青色 #0A0E27、深橙色 #FF5804、品牌橙色 #F5A623，以及系统无衬线字体。

银行卡扣款 UI 状态

状态	显示的卡片
需要 PIN	分步说明、交易参考编号
需要 AVS	以标签形式显示的必填账单地址字段
3DS 重定向	银行验证 URL，并提供直接链接
需要 OTP	银行消息，以及传递给 validate_charge 的 flw_ref
已完成	金额、状态徽章、交易参考编号和 Flutterwave 参考编号

虚拟账户 UI

虚拟账户卡片会在醒目大框中显示银行账号，并同时展示银行名称、账户类型（静态 / 动态）、货币、到期日期和订单参考编号。

账单支付 UI

工具	显示的卡片
pay_bill	账单收据 — 账单服务商、项目、客户 ID、金额、状态
get_bill_status	状态卡片，含以大号等宽字体显示的预付费令牌（电费），并附有分享说明

验证 UI

工具	显示的卡片
initiate_bvn_verification	同意卡片 — 客户姓名（仅显示 BVN 末 4 位）、一次性同意链接及打开按钮、分步说明
get_bvn_details	身份卡片 — 姓名、出生日期、性别、电话、NIN、籍贯州；BVN 部分遮蔽；若被标记，则显示红色监控名单徽章
resolve_bank_account	绿色已验证卡片 — 以大号文字显示账户名称，以及账号和银行代码
verify_card_bin	品牌主题色卡片（Visa 蓝色 / Mastercard 红色 / Amex 蓝色 / 其他品牌深色）— 品牌、类型徽章、发卡机构、国家

稳定币 UI

工具	显示的卡片
get_stablecoin_fee	蓝色主题费用卡片 — 币种对、固定费用或百分比明细、收款人实际收到的净额
send_stablecoin	转账卡片 — 截断的钱包地址、金额、状态徽章
convert_to_stablecoin	兑换卡片 — 扣款法币、目标稳定币、商户 ID、状态

外汇交易 UI

request_fx_quote/get_fx_quote 和 initiate_fx_trade/get_fx_trade 均会返回深海军蓝主题卡片：

状态	显示的卡片
报价 NEW / PROCESSING	产品徽章、状态标签、轮询说明
报价 READY	汇率、已批准数量、收到金额、到期时间、行动号召
报价 FAILED / EXPIRED	附带原因的错误消息
交易 NEW / PENDING	目标货币金额、轮询说明
交易 SETTLED	绿色结算横幅、目标货币金额、收款人、钱包入账说明
交易 FAILED	带有 response_message 的红色失败横幅

这些卡片兼容：

• Flutterwave Web App（此仓库的 app/）— 在聊天中以内嵌方式呈现
• MCP Inspector — 用于开发期间的测试
• 任何支持 HTML resource 内容类型的 MCP 客户端

---

贡献

欢迎贡献！请阅读我们的贡献指南，了解如何开始、开发准则以及如何提交拉取请求。

---

更新日志

所有重要变更都记录在 GitHub Releases 中。

---

安全

如果您发现安全漏洞，请不要公开提交问题。请直接发送邮件至 [email protected]。我们会尽快回复。

---

许可证

MIT © Abraham Olaobaju

完整文本请参阅 LICENSE。