README.md
Generic IMAP+SMTP MCP server for AI agents
mail-mcp
Generic IMAP+SMTP MCP server for AI agents — v0.2.0
Connect any email account to any AI agent (Claude, Gemini, Codex, Copilot, Vibe…). Intent-first design: high-level tools matching real user workflows, backed by a clean IMAP/SMTP core and a full triple admin surface (CLI + HTTP + Telegram).
Problem: AI agents have no native email access.
Why: IMAP+SMTP are universal, server-agnostic, no OAuth2 dance required.
How: FastMCP tools layer, pure stdlib SMTP, imapclient for IMAP, bw-env secrets.
Admin: mail-admin CLI + /admin/* HTTP routes + Telegram bot + SSH exec.
Architecture
mail_mcp/
├── config.yaml # Non-sensitive settings (hosts, ports, env var names)
├── config.py # @lru_cache loader + 3-tier secret resolution + admin env
│
├── admin/
│ ├── service.py # Shared backend: status, credentials CRUD, logs, summaries
│ ├── cli.py # mail-admin — Typer+Rich admin CLI
│ └── telegram.py # Telegram long-poll bot (in-process thread)
│
├── core/
│ ├── models.py # Pydantic: Message, MessageSummary, Folder, Address…
│ ├── imap_client.py # IMAPClient context-manager — search, fetch, flags, move
│ └── smtp_client.py # SMTPClient — send, reply, forward, draft
│
├── tools/
│ ├── guide.py # mail_guide() — agent orientation entry point
│ ├── read.py # check_inbox, daily_digest, search_messages, get_thread…
│ ├── compose.py # send_message, reply_message, forward_message, save_draft
│ └── manage.py # list_folders, mark_messages, move/archive/delete/spam
│
├── server.py # FastMCP root — mounts all sub-MCPs
├── http_app.py # Starlette app: MCP + /health + /admin/* routes
├── daemon.py # PID file lifecycle
└── cli.py # Typer CLI: serve, serve-http, stop, status, inbox, folders
Secret resolution (3 tiers)
1. Admin env file → /data/mail-admin.env (Docker volume, persistent credential overrides)
2. Process env → fastest (shell injection or MCP host)
3. bw-env login → zsh -l -c 'printf "%s" "${VAR}"' (Bitwarden GLOBAL_ENV_VARS)
Transports
| Transport | URL / Command | Description |
|---|---|---|
| HTTP (homelab) | https://mail.kpihx-labs.com/mcp |
Streamable-HTTP — production, always-on |
| stdio (fallback) | mail-mcp serve |
Direct process — local dev or when HTTP down |
Supported accounts
| Account | IMAP | SMTP | Server |
|---|---|---|---|
| Polytechnique (X) | webmail.polytechnique.fr:993 TLS |
:587 STARTTLS |
Zimbra |
More accounts: add an entry in config.yaml — no code change needed.
Quick start
# Install (editable for live dev)
uv tool install --editable .
# Admin CLI
mail-admin status # credential status table
mail-admin logs 20 # last 20 log lines
mail-admin credentials set poly <login> # live update without restart
mail-admin help # full capability map
# MCP stdio server
mail-mcp serve
# MCP HTTP server (port 8094)
mail-mcp serve-http
Admin surfaces
1. CLI — `mail-admin`
mail-admin status [--account <id>] # Rich table: env var, value (masked), source
mail-admin logs [N] # tail last N lines (default 40)
mail-admin credentials set <id> <login>
mail-admin credentials unset <id>
mail-admin help # full capability map
2. HTTP routes
| Route | Method | Description |
|---|---|---|
/health |
GET | Readiness probe — auth presence per account |
/admin/status |
GET | Full status: pid, transport, Telegram runtime, credentials |
/admin/help |
GET | Full capability map (CLI / HTTP / Telegram / SSH) |
/admin/logs?lines=40 |
GET | Tail of the admin log |
/admin/credentials/set |
POST | Set {account_id, login, password} |
/admin/credentials/unset |
POST | Clear credentials for {account_id} |
/mcp |
GET/POST | Streamable-HTTP MCP transport |
3. Telegram bot
Token env: TELEGRAM_MAIL_HOMELAB_TOKEN — auth gate: TELEGRAM_CHAT_IDS
| Command | Args | Effect |
|---|---|---|
/start /help |
— | Full capability map |
/status |
[account_id] |
Credential status |
/health |
— | Quick health summary |
/urls |
— | Transport URLs |
/logs |
[N] |
Last N log lines |
/credentials_set |
<id> <login> |
Live credential update |
/credentials_unset |
<id> |
Clear credentials |
/restart |
— | Graceful service restart |
4. SSH exec
docker compose exec -T mail-mcp mail-admin status
docker compose logs --tail=100 mail-mcp
MCP agent registration
Claude Code (`~/.claude.json`)
"mail-mcp": {
"url": "https://mail.kpihx-labs.com/mcp"
},
"mail-mcp--fallback"
Tools (12)
mail_guideAgent orientation entry point for email capabilities.check_inboxRetrieve messages from the inbox.daily_digestGenerate a summary of daily email activity.search_messagesSearch for specific emails based on criteria.get_threadRetrieve a full email thread.send_messageSend a new email message.reply_messageReply to an existing email message.forward_messageForward an email message to another recipient.save_draftSave an email as a draft.list_foldersList all available email folders.mark_messagesMark messages with specific flags.move_messageMove a message to a different folder.Environment Variables
TELEGRAM_MAIL_HOMELAB_TOKENToken for the Telegram bot integrationTELEGRAM_CHAT_IDSAuthorized chat IDs for Telegram bot accessConfiguration
claude_desktop_config.json
{"mail-mcp": {"url": "https://mail.kpihx-labs.com/mcp"}}Try it
→Check my inbox for any urgent emails from my manager.
→Summarize the emails I received today into a daily digest.
→Search for the latest invoice from AWS and forward it to my accountant.
→Reply to the last email in the thread regarding the project update with 'Confirmed, proceeding as planned.'
→Move all emails currently in the 'Promotions' folder to the 'Archive' folder.