Flutterwave

Interactúa con la API de Flutterwave para gestionar transacciones, generar enlaces de pago y manejar el soporte al cliente.

Documentación

mcp-flutterwave

CI npm version npm downloads Docker License: MIT Node.js MCP

Un servidor MCP (Model Context Protocol) que permite a los asistentes de IA interactuar con la API de Flutterwave: crear enlaces de pago, cobrar a clientes directamente, gestionar transferencias, cobrar mediante cuentas virtuales, pagar facturas y más.

Nota: Este servidor actualmente apunta a la API v3 de Flutterwave. El soporte para v4 llegará pronto.

También incluye una aplicación web integrada que se conecta al servidor MCP y te permite hablar con un asistente de Flutterwave impulsado por Claude directamente en tu navegador.


Contenido


Características

  • Checkout — Crea enlaces de pago alojados y desactívalos
  • Cargos Directos — Cobra a clientes mediante tarjeta, cuenta bancaria, dinero móvil, M-Pesa o USSD
  • Flujo completo de autenticación de tarjeta — PIN, AVS (Verificación de Dirección), redirección 3D Secure y validación de OTP manejados automáticamente
  • Validación de Cargos — Valida cargos basados en OTP con una herramienta dedicada
  • Transacciones — Verifica por ID o referencia, consulta la línea de tiempo de eventos, reenvía webhooks fallidos
  • Transferencias — Inicia transferencias individuales, gestiona beneficiarios
  • Planes de Pago — Crea y consulta planes de suscripción
  • Cuentas Virtuales — Genera números de cuenta dedicados para cobros por transferencia bancaria en NGN y GHS (estáticas o dinámicas)
  • Pago de Facturas — Paga aire, datos, TV por cable, electricidad, internet y más (Nigeria)
  • Operaciones FX — Convierte entre NGN, GHS y USD con cotizaciones en vivo (RFQ → operación en dos pasos)
  • Verificación — Verificación de identidad BVN, resolución de nombres de cuentas bancarias y consulta de BIN de tarjetas
  • Stablecoins — Envía USDC/USDT a billeteras Polygon, o convierte saldo fiduciario NGN/USD en stablecoins
  • Interfaz Enriquecida — Cada herramienta devuelve una tarjeta HTML con marca renderizada en línea en clientes compatibles
  • Aplicación Web — Una interfaz de chat independiente en el navegador impulsada por Claude + este servidor MCP

Instalación

npm

npm install -g mcp-flutterwave

npx (sin instalación)

npx mcp-flutterwave --tools=all

Docker

Descarga la imagen:

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

El servidor se comunica a través de stdio, por lo que debe ser lanzado por un cliente MCP, no ejecutarse de forma independiente. Configura Claude Desktop para usar la imagen Docker como servidor 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"
      ]
    }
  }
}

La bandera -i mantiene stdin abierto para que Claude Desktop pueda comunicarse con el servidor a través de stdio.

Requisitos: Node.js 20 o posterior (para npm/npx).


Herramientas Disponibles

Checkout

HerramientaDescripción
create_checkoutCrea un enlace de pago alojado de Flutterwave
disable_checkoutDesactiva un enlace de pago existente

Cargos Directos

HerramientaDescripción
charge_cardCobra directamente a una tarjeta de débito o crédito: maneja flujos de PIN, AVS, 3DS y OTP
charge_bank_accountDebita una cuenta bancaria (NGN / GHS)
charge_mobile_moneyDinero móvil: Ghana, Uganda, Ruanda, Zambia, África francófona
charge_mpesaCargo M-Pesa (KES)
charge_ussdCargo USSD (NGN)
validate_chargeValida un cargo pendiente usando OTP

Transacciones

HerramientaDescripción
read_transactionObtiene detalles de la transacción por ID
read_transaction_with_referenceObtiene detalles de la transacción por tx_ref
read_transaction_timelineConsulta la línea de tiempo de eventos de una transacción
resend_transaction_webhookReenvía un webhook fallido

Transferencias

HerramientaDescripción
create_transferInicia una transferencia bancaria
create_beneficiaryGuarda un nuevo beneficiario de transferencia
list_beneficiariesLista todos los beneficiarios guardados

Planes de Pago

HerramientaDescripción
create_payment_planCrea un plan de pago recurrente
get_payment_plansLista planes de pago con filtros opcionales

Cuentas Virtuales

HerramientaDescripción
create_virtual_accountCrea un número de cuenta bancaria dedicado para un cliente (NGN o GHS)
get_virtual_accountConsulta el estado y los detalles de una cuenta virtual por order_ref
update_virtual_accountVincula o actualiza el BVN en una cuenta virtual NGN
list_virtual_account_bulkLista todas las cuentas creadas en un lote masivo

Pago de Facturas

HerramientaDescripción
get_bill_categoriesLista las categorías de facturas disponibles (AIRTIME, CABLEBILLS, UTILITYBILLS, etc.)
get_bill_providersLista los emisores/proveedores de una categoría
get_bill_itemsLista los artículos pagables de un emisor específico
validate_bill_customerValida una cuenta de cliente antes del pago (número de medidor, smartcard, etc.)
pay_billEnvía un pago de factura
get_bill_statusConsulta el estado del pago y recupera tokens prepagados (electricidad)

Operaciones FX

HerramientaDescripción
request_fx_quoteEnvía una Solicitud de Cotización (RFQ) para una conversión de moneda
get_fx_quoteConsulta el estado de la cotización: espera a que esté READY antes de operar
initiate_fx_tradeConfirma una cotización READY y ejecuta la operación
get_fx_tradeConsulta el estado de la operación hasta que esté SETTLED o FAILED

Verificación

HerramientaDescripción
initiate_bvn_verificationInicia una verificación de identidad BVN: devuelve una URL de consentimiento del cliente de un solo uso
get_bvn_detailsRecupera los datos completos de identidad BVN después de que se otorgue el consentimiento
resolve_bank_accountConsulta el nombre del titular de una cuenta bancaria por número de cuenta
verify_card_binConsulta la marca, el tipo, el emisor y el país de la tarjeta a partir de los primeros 6 dígitos

Stablecoins

HerramientaDescripción
get_stablecoin_feeObtén la tarifa de transferencia antes de enviar: muestra el monto neto que recibe el destinatario
send_stablecoinEnvía USDC o USDT a una dirección de billetera Polygon
convert_to_stablecoinConvierte saldo fiduciario NGN o USD en USDC o USDT

Flujo de Cargo con Tarjeta

Los cargos directos con tarjeta son de varios pasos. La herramienta charge_card maneja cada etapa automáticamente y le indica a Claude qué hacer a continuación.

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

Parámetros de autorización

Cuando se necesita una segunda llamada, pasa authorization junto con los detalles originales de la tarjeta:

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

Tarjetas AMEX

Las transacciones con American Express requieren el campo card_holder_name además de los detalles estándar de la tarjeta.

Cifrado del payload

Los payloads de tarjeta se cifran con 3DES-ECB usando tu FLW_ENCRYPTION_KEY antes de enviarse a Flutterwave (requisito PCI DSS). El cifrado se maneja automáticamente: configura la variable de entorno y el servidor hace el resto.


Cuentas Virtuales

Las cuentas virtuales le dan a cada cliente un número de cuenta bancaria dedicado para hacer transferencias. Flutterwave notifica a tu webhook cuando llega un pago.

CaracterísticaNGNGHS
Dinámica (de un solo uso)✓ — configura amount, expira en ~1 hora✓ — usa frequency y duration
Estática (reutilizable)✓ — is_permanent: true, se requiere BVN✓ — is_permanent: true
BVN requeridoSolo cuentas estáticasNo

Cuenta estática NGN

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

Cuenta dinámica GHS

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

Después de la creación, guarda el order_ref: es la clave para recuperar o actualizar la cuenta mediante get_virtual_account y update_virtual_account.


Flujo de Pago de Facturas

El pago de facturas sigue un flujo de descubrimiento de 6 pasos. Omite validate_bill_customer para aire y datos móviles.

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

Categorías compatibles

CódigoDescripción
AIRTIMERecarga de aire móvil
MOBILEDATACompra de paquetes de datos
CABLEBILLSTV por cable (DSTV, GOTV, StarTimes)
INTSERVICESuscripciones a servicios de internet
UTILITYBILLSElectricidad (prepago y pospago)
TAXPagos de impuestos gubernamentales
DONATIONSDonaciones benéficas
TRANSLOGTransporte / logística
DEALPAYPagos de acuerdos
RELINSTInstituciones religiosas
SCHPBPagos escolares / educativos

El pago de facturas está disponible solo para Nigeria (country: NG).


Flujo de Operaciones FX

La conversión de moneda usa un flujo de dos pasos: cotización y luego operación. Las cotizaciones son válidas por 5 minutos y están disponibles solo entre semana (lunes a viernes).

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

Pares de moneda compatibles

ParVendeRecibe
NGN/USDNaira nigerianaDólar estadounidense
GHS/USDCedi ghanésDólar estadounidense
USD/NGNDólar estadounidenseNaira nigeriana

Estados de cotización

EstadoSignificado
NEWLa cotización se está calculando
READYTasa bloqueada: llama a initiate_fx_trade ahora
PROCESSINGSe ha iniciado una operación con esta cotización
EXPIREDPasó la ventana de 5 minutos: envía una nueva cotización
FAILEDPar no compatible, mínimo no alcanzado o límite de cuenta excedido

Estados de operación

EstadoSignificado
NEWOperación en cola
PENDINGEjecutando
SETTLEDFondos intercambiados y acreditados en la billetera de la moneda objetivo
FAILEDSaldo insuficiente o error de procesamiento

Restricciones clave

  • Operación mínima: equivalente a $1,000 USD en la moneda base
  • Vida útil de la cotización: 5 minutos desde su emisión (estado READY)
  • Uso único: cada cotización solo se puede usar para una operación
  • Cantidad aprobada: puede diferir de la cantidad solicitada debido a liquidez o límites de cuenta: usa siempre approved_quantity para la conciliación
  • Habilitación de cuenta: contacta a hi@flutterwavego.com para habilitar operaciones FX en tu cuenta

Verificación

Resolución de Cuenta Bancaria

Verifica los detalles de la cuenta de un destinatario antes de enviar una transferencia. Siempre muestra el nombre resuelto al usuario antes de continuar.

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

Códigos bancarios comunes: 044 Access Bank · 057 Zenith Bank · 058 GTBank · 033 UBA · 011 First Bank

Consulta de BIN de Tarjeta

Identifica los metadatos de la tarjeta a partir de los primeros 6 dígitos del número de tarjeta.

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

Las tarjetas AMEX identificadas mediante BIN requieren el campo card_holder_name al llamar a charge_card.

Verificación BVN (Nigeria)

Flujo de consentimiento en dos pasos: el cliente debe aprobar el intercambio de datos en el portal 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

Requiere habilitación de la cuenta Flutterwave: contacta a hi@flutterwavego.com. Si el cliente ya dio su consentimiento, initiate_bvn_verification devuelve url: null y puedes llamar a get_bvn_details de inmediato.


Stablecoins

Envía USDC o USDT a través de la red Polygon, o convierte saldos fiduciarios NGN/USD en stablecoins. Siempre llama a get_stablecoin_fee primero para que el usuario sepa el monto neto que recibirá el destinatario.

Transferencia de billetera a billetera

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

Conversión de fiduciario a stablecoin

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

Restricciones clave

RestricciónDetalle
RedSolo Polygon: sin Tron, Solana ni Stellar
MonedasUSDC y USDT
Formato de billeteraDirección EVM: 0x + 40 caracteres hexadecimales (42 en total)
Fuentes fiduciariasNGN o USD para convert_to_stablecoin; el stablecoin debe coincidir con currency para send_stablecoin
Tipo de tarifaTarifa fija para la misma moneda; tarifa porcentual para fiduciario → stablecoin

Aplicación Web

El directorio app/ contiene una interfaz de chat independiente en el navegador que envuelve este servidor MCP con un bucle de conversación impulsado por Claude.

Flutterwave MCP-UI Components

Cómo funciona

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

La aplicación web usa tres funciones avanzadas de uso de herramientas de Anthropic:

  • Búsqueda de herramientas — las herramientas no esenciales se difieren y se cargan bajo demanda, reduciendo el uso de tokens en ~85%
  • Llamada programática de herramientas — Claude puede escribir código que llama múltiples herramientas en secuencia sin inflar el contexto de la conversación
  • Ejemplos de uso de herramientas — input_examples seleccionados para cada herramienta mejoran la precisión de los parámetros de ~72% a ~90%

La aplicación devuelve una tarjeta de interfaz de marca enriquecida para cada respuesta de herramienta — enlaces de pago, detalles de transacción, estados de cargo, resúmenes de transferencia, cuentas virtuales, recibos de facturas — renderizados en línea en el chat.

Ejecutar la aplicación web

Requisitos previos

VariableRequeridaDescripción
FLW_SECRET_KEYSíTu clave secreta de Flutterwave
FLW_ENCRYPTION_KEYPara cargos con tarjetaTu clave de cifrado de Flutterwave
ANTHROPIC_API_KEYSíTu clave de API de Anthropic

Obtén tus claves desde el Panel de Flutterwave en Configuración → Claves de API.
Obtén tu clave de Anthropic desde la Consola de Anthropic.

Compilar e iniciar

# 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

Luego abre http://localhost:3000.

Scripts disponibles

ScriptDescripción
npm run buildCompilar solo el servidor MCP
npm run build:appCompilar solo la aplicación web
npm run build:allCompilar todo
npm run start:appIniciar la aplicación web (requiere una compilación previa)
npm run dev:appCompilar todo y luego iniciar la aplicación web
npm testEjecutar la suite de pruebas

Puerto

Establece la variable de entorno PORT para cambiar el valor predeterminado 3000.


Configuración del servidor MCP

Vía npm

npm install -g mcp-flutterwave

Vía GitHub

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

Variables de entorno

VariableRequeridaDescripción
FLW_SECRET_KEYSíTu clave secreta de Flutterwave
FLW_ENCRYPTION_KEYPara cargos con tarjetaTu clave de cifrado de Flutterwave (desde Panel → Configuración → API)

Uso con Claude Desktop

Agrega lo siguiente a tu claude_desktop_config.json. Consulta la guía de inicio rápido de MCP para más detalles.

Pasa --tools=all para habilitar todas las herramientas, o proporciona una lista separada por comas para restringir qué herramientas se registran.

Vía npm

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

Vía compilación local

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

Herramientas selectivas

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

Nombres de herramientas aceptados (usa all para habilitar todo):

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

Componentes MCP-UI

Cada herramienta devuelve una tarjeta HTML enriquecida junto con su respuesta de texto, impulsada por @mcp-ui/server. Las tarjetas usan los tokens de diseño de Flutterwave — azul marino #0A0E27, naranja profundo #FF5804, naranja de marca #F5A623, y la tipografía sans-serif del sistema.

Estados de interfaz para cargos con tarjeta

EstadoTarjeta mostrada
PIN requeridoInstrucciones paso a paso, referencia de transacción
AVS requeridoCampos de dirección de facturación requeridos como chips
Redirección 3DSURL de autenticación bancaria con enlace directo
OTP requeridoMensaje del banco, flw_ref para pasar a validate_charge
CompletadoMonto, insignia de estado, referencias de transacción y de Flutterwave

Interfaz de cuenta virtual

La tarjeta de cuenta virtual muestra el número de cuenta bancaria en un recuadro grande y prominente junto con el nombre del banco, tipo de cuenta (Estática / Dinámica), moneda, fecha de vencimiento y referencia de pedido.

Interfaz de pago de facturas

HerramientaTarjeta mostrada
pay_billRecibo de factura — proveedor, artículo, ID de cliente, monto, estado
get_bill_statusTarjeta de estado con token prepagado (electricidad) en texto monoespaciado grande, con nota para compartir

Interfaz de verificación

HerramientaTarjeta mostrada
initiate_bvn_verificationTarjeta de consentimiento — nombre del cliente (solo últimos 4 dígitos de BVN), enlace de consentimiento de un solo uso con botón de apertura, instrucciones paso a paso
get_bvn_detailsTarjeta de identidad — nombre, fecha de nacimiento, género, teléfono, NIN, estado de origen; BVN parcialmente enmascarado; insignia roja de lista de vigilancia si está marcado
resolve_bank_accountTarjeta verde verificada — nombre de cuenta en texto grande con número de cuenta y código bancario
verify_card_binTarjeta con colores de marca (azul Visa / rojo Mastercard / azul Amex / oscuro para otros) — marca, insignia de tipo, emisor, país

Interfaz de stablecoin

HerramientaTarjeta mostrada
get_stablecoin_feeTarjeta de tarifa con tema azul — par de monedas, tarifa fija o desglose porcentual, monto neto que recibe el destinatario
send_stablecoinTarjeta de transferencia — dirección de billetera truncada, monto, insignia de estado
convert_to_stablecoinTarjeta de conversión — moneda fiduciaria de débito, stablecoin objetivo, ID de comerciante, estado

Interfaz de operaciones FX

Tanto request_fx_quote/get_fx_quote como initiate_fx_trade/get_fx_trade devuelven tarjetas con tema azul marino oscuro:

EstadoTarjeta mostrada
Cotización NUEVA / EN PROCESOInsignia de instrumento, píldora de estado, instrucción de consulta
Cotización LISTATipo de cambio, cantidad aprobada, monto recibido, vencimiento, llamada a la acción
Cotización FALLIDA / VENCIDAMensaje de error con motivo
Operación NUEVA / PENDIENTEMonto en moneda objetivo, instrucción de consulta
Operación LIQUIDADABanner verde de liquidación, monto en moneda objetivo, destinatario, nota de crédito de billetera
Operación FALLIDABanner rojo de fallo con response_message

Las tarjetas son compatibles con:

  • Aplicación web de Flutterwave (app/ de este repositorio) — renderizadas en línea en el chat
  • MCP Inspector — para pruebas durante el desarrollo
  • Cualquier cliente MCP que admita el tipo de contenido resource con HTML

Contribuciones

¡Agradecemos las contribuciones! Lee nuestra Guía de contribución para obtener detalles sobre cómo comenzar, pautas de desarrollo y cómo enviar solicitudes de extracción.


Registro de cambios

Todos los cambios notables están documentados en Lanzamientos de GitHub.


Seguridad

Si descubres una vulnerabilidad de seguridad, no abras un problema público. En su lugar, envía un correo electrónico directamente a olaobajua@gmail.com. Responderemos lo antes posible.


Licencia

MIT © Abraham Olaobaju

Consulta LICENCIA para el texto completo.