breezykalama/mpesa-mcp-server

AI financial action infrastructure for African payment rails, with MCP tools, M-Pesa/Daraja integration, approvals, auditability, Redis rate limiting, PostgreSQL persistence, and a React operator dashboard. # M-Pesa MCP Server An experimental Model Context Protocol (MCP) server that lets an AI agent interact with guarded payment workflows through typed tools. The project is a production-shaped prototype for safe agent-assisted payments. It demonstrates how an agent can request payment actions, check transaction state, handle STK callbacks, generate receipts, ask revenue questions, and support operator approvals while payment execution remains isolated behind service interfaces and provider adapters. ## Current Status - Mock mode complete for safe local demos - Daraja sandbox STK Push supported - Daraja sandbox Transaction Status supported - Mock Airtel Money provider demonstrates multi-rail architecture - PostgreSQL persistence supported - Redis-backed rate limiting supported - Reconciliation engine supported - Operator dashboard API supported - Lightweight operator auth/RBAC supported - React operator dashboard supported for demos - CI is green on GitHub Actions ## Quick Demo ```bash uv sync uv run pytest uv run python scripts/smoke_mcp_tools.py docker compose up --build ``` The smoke script runs fully in memory and now demonstrates the legacy M-Pesa flow, generic Daraja-backed payment tools, and the mock Airtel Money rail. Docker Compose starts FastAPI, PostgreSQL, and Redis in mock payment mode. ## Project Purpose This project is a backend architecture prototype for agent-assisted payment operations, starting with M-Pesa. It is designed to answer questions like: - "Initiate an STK push for this invoice." - "Check the status of this checkout request." - "Generate a receipt for this completed payment." - "Show today's M-Pesa revenue." - "Show today's failed transactions." The emphasis is on safe tool boundaries, testable service layers, and replaceable infrastructure. Mock mode remains the default for local demos and CI. Daraja/M-Pesa is the first real payment rail. The project also includes a mock Airtel Money provider to demonstrate that the servi …