Skip to main content
Glama
momo-xof-mcp

momo-xof-mcp

momo-xof-mcp

MCP server for West African mobile money (XOF zone). Give your AI agent the ability to initiate and track mobile money payments across the major mobile money operators in the eight UEMOA countries.

Status: v0.1. All three tools work against the CinetPay sandbox. Sandbox only — the production base URL has not been established yet, and the server refuses any non-sandbox endpoint while MOMO_ENV=sandbox.

Three tools, eight countries, against the live CinetPay sandbox

Generated from a real run: python scripts/demo.py --fast > t.txt && python scripts/make_gif.py t.txt. Nothing in it is mocked up.

Why this exists

Mobile money is how most of West Africa pays. Dozens of SDKs exist for these APIs in PHP, Node, Python and Flutter — but no MCP server. An agent built today cannot request a payment in XOF without custom integration work.

momo-xof-mcp closes that gap for the franc CFA zone. (For East Africa, see mpesa-mcp, which covers M-Pesa and Africa's Talking.)

Countries in scope: Benin, Burkina Faso, Côte d'Ivoire, Guinea-Bissau, Mali, Niger, Senegal, Togo.

Related MCP server: momo-mcp

Tools

Tool

Description

momo_list_operators

List supported operators and countries

momo_initiate_payment

Request a payment from a customer's mobile wallet

momo_check_payment_status

Check the status of a payment request

momo_initiate_payment requests a payment; it does not confirm one. Final status arrives asynchronously — always poll with momo_check_payment_status.

Usage

Ask for a payment. The response below is a real sandbox response, trimmed:

{
  "status": "accepted",
  "is_final": false,
  "provider_status": "INITIATED",
  "merchant_reference": "CMD-2026-0042",
  "transaction_id": "69fe371559c34c6f98971be5c8f4e4df",
  "payment_url": "https://secure.cinetpay.net/checkout/1f1b6850f7e1...",
  "what_this_means": "The payment has been REQUESTED, not completed.
                      No money has moved yet."
}

Send the customer to payment_url. Later, check what became of it — with your own reference or the returned transaction_id, both work:

{
  "status": "failed",
  "is_final": true,
  "provider_status": "FAILED",
  "merchant_reference": "CMD-2026-0042",
  "customer": null,
  "what_this_means": "This payment will not complete. The outcome is final."
}

Four things that will bite you

These are not hypothetical. Each one cost us a debugging session against the live sandbox, and each is now enforced in code.

A successful call is not a successful payment. momo_initiate_payment returning "accepted" means the aggregator took the request. The customer has not paid. Nothing has moved. Treat payment_url as an invitation, not a receipt.

An abandoned payment ends up failed, and that is final. It does not linger in a pending state waiting for the customer to come back. An agent that polls until it sees something other than "pending" will poll forever. Read is_final.

Retrying with the same reference is safe. The aggregator refuses to create a second payment for a reference it already knows, so a retry after a network timeout cannot double-charge. You will get an error, not a duplicate — call momo_check_payment_status with that reference to learn what happened to the first attempt.

Number prefixes do not identify a payment service. Wave runs on any national number and owns no prefix range at all. Portability breaks prefix-to-operator mapping anyway. momo_list_operators returns prefix hints for input validation only; the aggregator decides the real routing.

Install

pip install momo-xof-mcp

Claude Desktop / Claude Code configuration:

{
  "mcpServers": {
    "momo-xof": {
      "command": "python",
      "args": ["-m", "momo_xof_mcp"],
      "env": {
        "MOMO_ENV": "sandbox"
      }
    }
  }
}

Credentials go in .env. See .env.example.

Installing the package also provides a momo-xof-mcp console script, which starts the same stdio server with no arguments.

Testing with MCP Inspector

Use the console script, not python -m momo_xof_mcp:

npx @modelcontextprotocol/inspector --cli /path/to/venv/bin/momo-xof-mcp \
  --method tools/list

The Inspector does not forward arguments to the program it launches. Point it at python with -m momo_xof_mcp and Python starts with no script, drops into REPL mode, reads the JSON-RPC handshake from stdin and tries to evaluate it as Python — you get NameError: name 'true' is not defined and then a handshake timeout. The console script takes no arguments, so the problem disappears.

MCP clients such as Claude Desktop pass arguments correctly, so the python -m momo_xof_mcp form above is fine for them.

Configuration

Variable

Required

Notes

MOMO_API_KEY

yes

CinetPay API key

MOMO_API_PASSWORD

yes

Set it on the dashboard first — it is unset by default

MOMO_CALLBACK_URL

yes

The aggregator rejects a payment without it

MOMO_SUCCESS_URL

yes

Max 120 characters

MOMO_FAILED_URL

yes

Max 120 characters

MOMO_ENV

no

sandbox (default) or production

MOMO_BASE_URL

no

Defaults to the sandbox host

MOMO_MAX_AMOUNT

no

Server-side ceiling in whole XOF, default 50000

MOMO_TIMEOUT

no

Seconds, default 30

Whitelist your server's public IP on the CinetPay dashboard, under API & sécurité → Liste Blanche IP. The dashboard claims an empty whitelist means "accessible from any IP". It does not: an empty whitelist rejects every call. If you develop from a dynamic IP, expect to update this often, or ask CinetPay support to lift it for your sandbox account.

Safety

This server can move real money. It ships with:

  • a server-side amount ceiling (MOMO_MAX_AMOUNT), enforced before any network call

  • a sandbox lock that refuses any non-sandbox endpoint while MOMO_ENV=sandbox

  • caller-supplied idempotency references, never generated for you

  • unknown arguments rejected rather than silently ignored, so a mistyped field on a payment request fails loudly instead of falling back to a default

  • explicit status mapping: an aggregator status this server does not recognise raises, rather than being rounded to the nearest plausible one

  • masked phone numbers, in logs and in tool output alike

  • amounts as whole integers only — the CFA franc has no decimal subunit

Roadmap

v0.2 — disbursements, additional aggregators. v0.3 — inbound webhooks, transaction history.

Licence

MIT. Built by SOTECHDI, Ouagadougou, Burkina Faso.


Français

Serveur MCP pour le mobile money en zone franc CFA (XOF) : les principaux opérateurs des huit pays de l'UEMOA. Trois outils — lister les opérateurs, initier un paiement, consulter un statut. Version 0.1, les trois outils répondent en sandbox. Documentation complète en anglais ci-dessus.

Available Tools

3 tools
momo_check_payment_statusA
Read-onlyIdempotent

Check what became of a payment you requested earlier. Read-only: it never moves money and never changes anything. Accepts either the merchant reference you supplied when initiating, or the transaction_id returned then. Returns a stable status plus the aggregator's own status and code, and says whether the outcome is final. A payment that was requested but never completed by the customer ends up FAILED, which is final — it does not stay pending forever. The customer's phone number is returned masked, never in full.

Inputs: reference (required). Returns: result

momo_initiate_paymentA
DestructiveIdempotent

Request a mobile money payment from a customer in the XOF zone. IMPORTANT: this REQUESTS a payment, it never confirms one. A successful call means the aggregator accepted the request and returned a payment link; the customer has not paid yet and no money has moved. The final outcome arrives asynchronously and must be checked separately. Returns a payment_url that the customer must open to complete the payment, plus the transaction identifiers needed to reconcile it. The caller must supply a unique reference for idempotency; it is never generated silently. Amounts are whole XOF: the franc has no decimals. A server-side ceiling rejects amounts above the configured maximum.

Inputs: amount (required), reference (required), description (required), client_email (required), +4 more. Returns: result

momo_list_operatorsA
Read-onlyIdempotent

List the countries of the West African CFA franc (XOF) zone and the mobile money services available in each. For every one of the eight UEMOA countries it returns the ISO code, international dialing code, national number length and E.164 format, then the payment services on offer, and finally optional prefix hints. Purely static: no network call, no credentials needed. Use it before initiating a payment to check that a country and a service are in scope and that a phone number has the expected shape. Payment services are unrelated to number prefixes: independent wallets such as Wave run on any national mobile number. Prefix hints, when present, map a prefix to a telecom network only, are defeated by number portability, and must never be used to route a payment.

Inputs: country. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.5/5.0

    Scored across 3 tools

    Disambiguation5/5

    The three tools occupy clearly separate phases of a payment flow: static coverage lookup, payment initiation, and status polling. Descriptions explicitly disambiguate initiation (request-only, returns a link) from status checking (read-only, resolves outcome), so an agent cannot easily confuse them.

    Naming Consistency5/5

    All three follow the same pattern: a shared momo_ namespace prefix plus verb_noun (list_operators, initiate_payment, check_payment_status). No mixed casing or inconsistent verb styles.

    Tool Count5/5

    Three tools is exactly the surface needed for a narrow mobile-money payment scope: discover coverage, start a payment, check its result. Each tool earns its place and nothing extraneous is exposed.

    Completeness4/5

    The core lifecycle (coverage discovery -> initiate -> async status) is fully covered, including idempotency references and finality of FAILED states. Gaps remain around refunds, cancellation, and listing past transactions, but agents can work around these for the stated request-and-reconcile purpose.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      MCP server that connects AI assistants to the CinetPay API for mobile money payments across Africa, enabling balance checks, payment initialization, transfers, and more.
      7
      18 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      An MCP server for Mobile Money in Francophone West Africa that enables AI agents to make payments via MTN MoMo (sandbox) using tools like request_payment, check_payment_status, and disburse_payment.
      1
      MIT