MailAfrica Agent

MailAfrica Agent is a Python service that gives MailAfrica agentic capabilities. It provides two core features:

MCP Server — Exposes the entire MailAfrica API (send/receive email, domains, webhooks, wallet) as Model Context Protocol tools, letting AI assistants like Claude, Cursor, and others manage email programmatically.
Auto-Reply Agent — When inbound email arrives via webhook, an LLM reads the conversation and generates a contextual reply. Replies can be sent automatically or saved as drafts for review.

What is MCP?

The Model Context Protocol (MCP) is an open standard that lets AI assistants call external tools. MailAfrica Agent implements an MCP server so you can talk to your email from Claude Desktop, Claude Code, Cursor, or any MCP-compatible client.

What You Can Do

With MailAfrica Agent you can:

Send emails from verified domains
Read inbound messages and manage receiving addresses
Set up webhooks to get notified of new mail
Verify sending domains (DKIM, CNAME records)
Check your wallet balance in TZS
Configure auto-reply with custom personas per address
Draft or auto-send AI-generated replies

Architecture Overview

┌──────────────────────────────────────────────────────────┐
│                    MCP Clients                           │
│  (Claude Desktop, Cursor, Claude Code, etc.)            │
└──────────────────────┬───────────────────────────────────┘
                       │ stdio (MCP protocol)
┌──────────────────────▼───────────────────────────────────┐
│               MailAfrica Agent                           │
│  ┌─────────────┐  ┌──────────┐  ┌────────────────────┐  │
│  │ MCP Server  │  │ Webhook  │  │ Auto-Reply Agent   │  │
│  │ (FastMCP)   │  │ (FastAPI)│  │ (Ngamia LLM)       │  │
│  └──────┬──────┘  └────┬─────┘  └────────┬───────────┘  │
│         │              │                  │               │
│         └──────────────┴──────────────────┘               │
│                        │                                  │
│               ┌────────▼────────┐                        │
│               │   SQLite Store  │                        │
│               │  (WAL mode)     │                        │
│               └─────────────────┘                        │
└──────────────────────┬───────────────────────────────────┘
                       │ HTTPS
        ┌──────────────┴──────────────┐
        │                             │
┌───────▼────────┐          ┌─────────▼───────┐
│ MailAfrica API │          │ Ngamia LLM API  │
│ api.mailafrica │          │ api.ngamia.cc   │
│ .online        │          │                 │
└────────────────┘          └─────────────────┘

Tech Stack

Component	Technology
Language	Python 3.11+
MCP Server	FastMCP (`mcp` SDK)
Webhook Server	FastAPI + Uvicorn
HTTP Client	httpx
LLM Gateway	Ngamia (OpenAI-compatible)
Conversation Memory	SQLite (aiosqlite, WAL mode)
Settings	Pydantic Settings
Container	Docker (multi-stage)
CI/CD	GitHub Actions

Quick Links

Quickstart Guide — Get running in 5 minutes
MCP Tools Reference — All 20 tools documented
Auto-Reply Agent — Configure AI replies
Deployment — Docker, VPS, and CI/CD setup

Quickstart