airtime_send
Send airtime top-up to MTN/Safaricom/Airtel/Vodafone subscribers. Use for NGO field incentives, survey rewards, agent payouts. No real airtime sent in sandbox mode (AT_USERNAME=sandbox).
LABSCO SUMMARY
The M-Pesa surface an agent actually needs: collect, disburse, reconcile, and check who you are paying.
It goes past the usual STK-push wrapper — reversal, KRA remittance, Bill Manager invoicing and SIM-swap screening are all here, which is what makes it usable for real settlement rather than demos. Several tools return their result to a callback URL rather than inline, so you need a reachable endpoint before those paths work.
What it is
An MCP server for East African fintech APIs — M-Pesa through Safaricom's Daraja and messaging through Africa's Talking. It covers collection, disbursement, reconciliation and fraud signals, so an agent can take a payment and confirm it landed without custom integration work.
What you get
- mpesa_stk_push and mpesa_stk_query — send a payment prompt to a customer's phone, then poll the result; ResultCode 0 is success, 1032 cancelled, 1037 timed out
- mpesa_b2c — disburse from your shortcode to a phone, for payroll, field incentives, agent float or survey rewards
- mpesa_business_paybill, mpesa_business_buygoods and mpesa_business_pochi — pay another paybill, a till, or a Pochi la Biashara wallet
- mpesa_b2b_express_checkout — a USSD push to a merchant till for merchant-to-merchant payment
- mpesa_transaction_status, mpesa_account_balance and mpesa_query_org_info — look up any transaction by receipt, read the shortcode balance, and validate a destination shortcode before sending
- mpesa_pull_transactions — pull C2B transactions for reconciliation, up to a 48-hour range per call
- mpesa_reversal — reverse a payment sent to the wrong number or for the wrong amount
- mpesa_dynamic_qr — generate a QR code with the amount pre-filled, returned as base64
- mpesa_ratiba_create — a standing order the customer authorises once, for subscriptions or rent
- mpesa_bill_manager_optin, mpesa_bill_manager_invoice and mpesa_bill_manager_cancel — enrol once, then issue and cancel invoices customers pay by SMS link
- mpesa_tax_remittance — remit to the Kenya Revenue Authority against a Payment Registration Number
- mpesa_sim_swap_query and mpesa_imsi_query — recent SIM-swap and registration signals on a Safaricom number, before a high-value payout
- sms_send and airtime_send — SMS to 1–1000 recipients and airtime top-ups across Kenya, Nigeria, Ghana, Tanzania, Uganda, Rwanda and more
- get_model_hint — the model the project recommends pairing with these tools
Requirements
Daraja credentials — MPESA_CONSUMER_KEY, MPESA_CONSUMER_SECRET, MPESA_SHORTCODE, MPESA_PASSKEY and MPESA_CALLBACK_URL — with MPESA_SANDBOX set to false for production. The business-to-business, reversal, balance and status tools additionally need MPESA_INITIATOR_NAME and MPESA_SECURITY_CREDENTIAL, and deliver their result asynchronously to MPESA_RESULT_URL. SMS and airtime need AT_USERNAME and AT_API_KEY. Install with pip install mpesa-mcp or run it with uvx mpesa-mcp over stdio.
Setup effort
One command plus a key — pip install mpesa-mcp, then supply credentials
USE CASES
01
Taking a payment from a customer
Send the PIN prompt to their phone, then poll for the result a few seconds later.
02
Paying field workers
Check the shortcode balance, disburse to each phone, and top up airtime where that is the agreed incentive.
03
Screening a payout before it goes out
Check the number's SIM-swap history and registration age before releasing a high-value transfer.
04
Reconciling yesterday's takings
Pull the C2B transactions for the window and look up anything that does not match by receipt number.
05
Fixing a payment sent to the wrong number
Reverse the transaction and notify the customer by SMS.
23 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
get_model_hint
Returns the recommended AI model for using mpesa-mcp tools. Call this first when selecting a model to pair with mpesa-mcp.
mpesa_account_balance
Query current balance of the business M-Pesa account (shortcode/till). Result delivered async to MPESA_RESULT_URL. Requires MPESA_INITIATOR_NAME and MPESA_SECURITY_CREDENTIAL.
mpesa_b2b_express_checkout
Initiate USSD Push to till — enables merchant-to-merchant payments. Recipient merchant receives a USSD prompt to confirm payment from their till. Use for wholesale supplier payments between Lipa Na M-PESA merchants. Requires MPESA_INITIATOR_NAME and MPESA_SECURITY_CREDENTIAL.
mpesa_b2c
Business To Customer disbursement — send money from shortcode to phone. Use for payroll, NGO field incentives, agent float, survey rewards. Result delivered async to MPESA_RESULT_URL. Requires MPESA_INITIATOR_NAME and MPESA_SECURITY_CREDENTIAL env vars.
mpesa_bill_manager_cancel
Cancel an outstanding Bill Manager invoice. Customer will no longer be able to pay the cancelled invoice. Use when an order is cancelled or a duplicate invoice was created.
mpesa_bill_manager_invoice
Create a Bill Manager invoice — customer receives SMS with payment link. They can pay directly via M-PESA by clicking the link or using the paybill. Returns invoice ID. Use mpesa_bill_manager_cancel to void outstanding invoices.
mpesa_bill_manager_optin
Enrol your business in M-PESA Bill Manager. Must be called once before creating invoices. After opt-in, customers can pay your invoices directly via M-PESA.
mpesa_business_buygoods
Pay from business shortcode to a till/buy-goods number. Requires MPESA_INITIATOR_NAME and MPESA_SECURITY_CREDENTIAL.
mpesa_business_paybill
Pay directly from business shortcode to another paybill number. Use for supplier payments, utility bills, inter-business transfers. Requires MPESA_INITIATOR_NAME and MPESA_SECURITY_CREDENTIAL.
mpesa_business_pochi
Pay from business shortcode to a Pochi la Biashara micro-SME wallet. Used for micro-enterprise supplier payments and informal sector settlements. Requires MPESA_INITIATOR_NAME and MPESA_SECURITY_CREDENTIAL.
mpesa_dynamic_qr
Generate a Dynamic M-PESA QR code for a specific payment amount. Customer scans QR with their M-PESA app — amount pre-fills automatically. Returns base64-encoded QR image. Use for receipts, invoices, POS displays.
mpesa_imsi_query
Verify a Safaricom number — returns registration date, SIM age, last swap, and hashed IMSI. Enhanced KYC/AML signal for financial services compliance. Older SIMs with no recent swaps have lower fraud risk. Returns data suitable for risk scoring without exposing raw IMSI.
mpesa_pull_transactions
Pull all C2B transactions for reconciliation within a date range. Returns customer payments to your shortcode for audit and reconciliation. Max range: 48 hours per call. Max 10,000 records per call.
mpesa_query_org_info
Validate a shortcode — returns the registered name and tariff type. Use before sending B2B payments to confirm the destination shortcode is correct. Prevents accidental payments to wrong paybill numbers.
mpesa_ratiba_create
Create an M-PESA Ratiba standing order — automated recurring payments. Customer authorizes once; payments happen automatically on schedule. Perfect for subscription billing, rent collection, loan repayments, SACCO contributions. Returns a standing order ID to manage/cancel later.
mpesa_reversal
Reverse an erroneous M-Pesa transaction. Use when a payment was sent to the wrong number or wrong amount. Requires MPESA_INITIATOR_NAME and MPESA_SECURITY_CREDENTIAL. Result delivered async to MPESA_RESULT_URL.
mpesa_sim_swap_query
Check if a phone number's SIM card was recently swapped. Critical fraud prevention signal — SIM swaps often precede account takeovers. Use before high-value B2C disbursements to verify recipient identity is stable. Returns swap status and last swap date.
mpesa_stk_push
Trigger M-Pesa STK Push — sends payment prompt to customer's phone. Customer enters M-PESA PIN to complete payment. Returns CheckoutRequestID; poll mpesa_stk_query after 10-30 seconds.
mpesa_stk_query
Check STK Push status. Poll 10-30s after mpesa_stk_push. ResultCode 0 = success, 1032 = cancelled, 1037 = timed out.
mpesa_tax_remittance
Remit tax directly from M-PESA business account to Kenya Revenue Authority. Provide the KRA Payment Registration Number (PRN) as account_reference. KRA shortcode: 572572. Requires MPESA_INITIATOR_NAME and MPESA_SECURITY_CREDENTIAL.
mpesa_transaction_status
Query status of any M-Pesa transaction by receipt number. Requires MPESA_INITIATOR_NAME and MPESA_SECURITY_CREDENTIAL. Result delivered async to MPESA_RESULT_URL.
sms_send
Send SMS to 1-1000 recipients via Africa's Talking. Works across Kenya, Nigeria, Ghana, Tanzania, Uganda, Rwanda and 15+ more. Returns per-recipient status and cost breakdown.
BEFORE YOU INSTALL
What to know first
Tools you get
23 tools when we connected. The documentation names only five; the undocumented eighteen include the money-moving tools, such as mpesa_b2c, mpesa_reversal and mpesa_business_paybill, plus SIM-swap and IMSI queries.
Requires
- uvx on PATH
- MPESA_CONSUMER_KEY in your environment
- MPESA_CONSUMER_SECRET in your environment
- MPESA_SHORTCODE in your environment
- MPESA_PASSKEY in your environment
- AT_USERNAME in your environment
- AT_API_KEY in your environment
- MPESA_INITIATOR_NAME in your environment
- MPESA_SECURITY_CREDENTIAL in your environment
Where it runs
Both documented clients run the server on your machine.
CONTEXT COST
Moderate Standing cost
Rated by the size of the 23 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
Connect your client
Server setup
TERMINAL
pip install mpesa-mcpMCP Clients
Claude Desktop
CLAUDE DESKTOP · JSON
{
"mcpServers": {
"mpesa": {
"command": "uvx",
"args": [
"mpesa-mcp"
],
"env": {
"MPESA_CONSUMER_KEY": "<YOUR_MPESA_CONSUMER_KEY>",
"MPESA_CONSUMER_SECRET": "<YOUR_MPESA_CONSUMER_SECRET>",
"MPESA_SHORTCODE": "174379",
"MPESA_PASSKEY": "<YOUR_MPESA_PASSKEY>",
"MPESA_CALLBACK_URL": "<YOUR_SERVER_URL>/mpesa/callback",
"MPESA_SANDBOX": "true",
"AT_USERNAME": "sandbox",
"AT_API_KEY": "<YOUR_AT_API_KEY>"
}
}
}
}MPESA_INITIATOR_NAME and MPESA_SECURITY_CREDENTIAL are the initiator credentials the B2C payout tools need, separate from the STK Push credentials. Add them to this env block too.
Claude Code
CLAUDE CODE · TERMINAL
claude mcp add mpesa -- uvx mpesa-mcpThis command sets no variables. As the project says, set them in your shell before running claude: MPESA_CONSUMER_KEY, MPESA_CONSUMER_SECRET, MPESA_SHORTCODE, MPESA_PASSKEY, MPESA_CALLBACK_URL, MPESA_SANDBOX, AT_USERNAME and AT_API_KEY — plus MPESA_INITIATOR_NAME and MPESA_SECURITY_CREDENTIAL for the B2C payout tools.
