<div align="center">

# 💳 mcp-african-markets

**MCP servers for African markets — agentic tooling for payments, reconciliation, and public data.**

[![CI](https://github.com/mutheejj/mcp-african-markets/actions/workflows/ci.yml/badge.svg)](https://github.com/mutheejj/mcp-african-markets/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Node](https://img.shields.io/badge/node-20%2B-green)](package.json)
[![Sponsor](https://img.shields.io/badge/Sponsor-%E2%9D%A4-EA4AAA?logo=githubsponsors)](https://github.com/sponsors/mutheejj)

M-Pesa · Mobile-money reconciliation · County data · Built agent-first

</div>

---

## Why

African fintech runs on M-Pesa, bank rails, and a patchwork of public portals — but almost none of it speaks to AI agents. If your agent can't call Daraja or reconcile a till, it can't do real work for millions of users.

**mcp-african-markets** ships focused [Model Context Protocol](https://modelcontextprotocol.io) servers so any MCP-aware agent gets first-class African-market tools.

## Servers

| Server | Status | What your agent can do |
|--------|--------|----------------------|
| **daraja** | 🚧 in progress | Initiate B2C/B2B payouts, query transaction status, validate phone numbers |
| **reconcile** | 🚧 in progress | Match M-Pesa statements against ledger CSVs, surface discrepancies |
| **county-data** | 📋 planned | Structured lookups for county public data |
| **kra** | 📋 planned | PIN validation helpers and filing-status lookups |

## Quickstart

```bash
npx mcp-african-markets --server daraja
```

Wire it into any MCP client:

```json
{
  "mcpServers": {
    "african-markets": {
      "command": "npx",
      "args": ["-y", "mcp-african-markets", "--server", "daraja"],
      "env": {
        "DARAJA_CONSUMER_KEY": "your-key",
        "DARAJA_CONSUMER_SECRET": "your-secret",
        "DARAJA_ENV": "sandbox"
      }
    }
  }
}
```

Defaults to **sandbox**. Production requires explicit opt-in (`DARAJA_ENV=production`) — agents should not move real money by accident.

## Design principles

1. **Sandbox by default** — money-moving tools are opt-in, loudly
2. **Read-only where possible** — reconciliation and lookups never mutate state
3. **Idempotency keys everywhere** — agents retry; payouts must not double-fire
4. **Local-first** — works offline against cached statements

## Status

🚧 **v0.x — early development.** The daraja server skeleton and sandbox auth flow are landing first.

## Roadmap

- [x] Project scaffold + MCP server template
- [ ] daraja: sandbox auth + STK push + transaction status
- [ ] reconcile: statement parser + fuzzy matcher
- [ ] county-data: first datasets
- [ ] kra: PIN validation helpers
- [ ] Example agent walkthroughs

## Who is this for

- Fintech teams building **agent-powered ops** on African rails
- Hackathon teams who want working payments tools on day one
- Developers who believe **agents should work everywhere**, not just in Silicon Valley

## Contributing

PRs welcome — new MCP servers, dataset contributions, and sandbox fixtures especially.

## 💖 Support

I build tools for the multi-agent era in the open. If this saves you time, [consider sponsoring](https://github.com/sponsors/mutheejj).

<div align="center">

MIT © [John Muthee](https://github.com/mutheejj)

</div>