io.github.gabrielmahia/mpesa-mcp

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.

Check STK Push status. Poll 10-30s after mpesa_stk_push. ResultCode 0 = success, 1032 = cancelled, 1037 = timed out.

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.

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.

Pay from business shortcode to a till/buy-goods number. Requires MPESA_INITIATOR_NAME and MPESA_SECURITY_CREDENTIAL.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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).

Returns the recommended AI model for using mpesa-mcp tools. Call this first when selecting a model to pair with mpesa-mcp.