Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mail-mcp Give me a daily digest of my recent emails"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Generic IMAP+SMTP MCP server for AI agents — v0.2.4
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.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, folders1. 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)Related MCP server: Email MCP Server
Transport | URL / Command | Description |
HTTP (homelab) |
| Streamable-HTTP — production, always-on |
stdio (fallback) |
| Direct process — local dev or when HTTP down |
Account | IMAP | SMTP | Server |
Polytechnique (X) |
|
| Zimbra |
More accounts: add an entry in config.yaml — no code change needed.
# 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> <pass> # live update without restart
mail-admin help # full capability map
# MCP stdio server
mail-mcp serve
# MCP HTTP server (port 8094)
mail-mcp serve-httpmail-adminmail-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> <pass>
mail-admin credentials unset <id>
mail-admin help # full capability mapRoute | Method | Description |
| GET | Readiness probe — auth presence per account |
| GET | Full status: pid, transport, Telegram runtime, credentials |
| GET | Full capability map (CLI / HTTP / Telegram / SSH) |
| GET | Tail of the admin log |
| POST | Set |
| POST | Clear credentials for |
| GET/POST | Streamable-HTTP MCP transport |
Token env: TELEGRAM_MAIL_HOMELAB_TOKEN — auth gate: TELEGRAM_CHAT_IDS
Command | Args | Effect |
| — | Full capability map |
|
| Credential status |
| — | Quick health summary |
| — | Transport URLs |
|
| Last N log lines |
|
| Live credential update |
|
| Clear credentials |
| — | Graceful service restart |
docker compose exec -T mail-mcp mail-admin status
docker compose logs --tail=100 mail-mcp~/.claude.json)"mail-mcp": {
"url": "https://mail.kpihx-labs.com/mcp"
},
"mail-mcp--fallback": {
"command": "zsh",
"args": ["-l", "-c", "/home/kpihx/.local/bin/mail-mcp serve"]
}~/.codex/config.toml)[mcp_servers.mail_mcp]
url = "https://mail.kpihx-labs.com/mcp"
[mcp_servers.mail_mcp_fallback]
command = "zsh"
args = ["-l", "-c", "/home/kpihx/.local/bin/mail-mcp serve"]~/.vibe/config.toml)[[mcp_servers]]
name = "mail"
transport = "http"
url = "https://mail.kpihx-labs.com/mcp"
[[mcp_servers]]
name = "mail_fallback"
transport = "stdio"
command = "zsh"
args = ["-l", "-c", "/home/kpihx/.local/bin/mail-mcp serve"]~/.gemini/settings.json)"mcpServers": {
"mail-mcp": { "url": "https://mail.kpihx-labs.com/mcp" },
"mail-mcp--fallback": {
"command": "zsh",
"args": ["-l", "-c", "/home/kpihx/.local/bin/mail-mcp serve"]
}
}Tool | Intent |
| Agent orientation — start here |
| Unread count + last N summaries |
| Structured morning overview |
| Browse a folder |
| Full body by UID |
| Flexible search (query, sender, date, flags) |
| Unread shortcut |
| Full thread by Message-ID |
| New email (+ auto copy to |
| Reply by UID (+ auto copy to |
| Forward by UID (+ auto copy to |
| Draft to Drafts folder |
| All IMAP folders |
| Alias for |
| Create IMAP folder |
| Rename IMAP folder |
| Delete IMAP folder |
| Seen / flagged / answered flags |
| Move UIDs to folder |
| Move to Archive |
| Move to Trash |
| Permanent delete + expunge |
| Move to Spam/Junk |
| Download to file (default) or ingest as Base64 ( |
| Alias for |
Credentials are never stored in config.yaml — only env var names.
Secrets live in Bitwarden (GLOBAL_ENV_VARS) and are injected via bw-env / login shell.
Admin credential overrides persist in /data/mail-admin.env (Docker volume) — never committed.
No OAuth2, no refresh token storage — IMAP password auth via TLS only.
See deploy/ for docker-compose.yml and .env.example.
# Required env vars
X_LOGIN=your_imap_username
X_PASS=your_imap_password
TELEGRAM_MAIL_HOMELAB_TOKEN=<bot_token> # optional
TELEGRAM_CHAT_IDS=<comma,separated,ids> # optional
MAIL_MCP_ADMIN_ENV_FILE=/data/mail-admin.envGitLab CI auto-deploys master to the homelab runner via docker compose up -d --build.
This server cannot be deployed
Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.
Email inboxes for AI agents: send, receive, reply, search, and manage threaded email over MCP.
Your agent needs a mailbox of its own — to receive, thread, draft and send, with attachments, without borrowing your personal inbox or your company's SMTP. **What you can ask for** • "Create an inbox for this agent and tell me its address." • "Read the new messages in this thread and draft a reply." • "Send this message with the attachment and wait for the response." • "Search this inbox for everything from that domain." • "Show delivery metrics and the events on this inbox." **How to use it** Point any MCP client at https://mcp.aisa.one/mail/mcp and sign in with OAuth — there is no key to create or paste. 49 tools: create and delete inboxes, list and read messages, raw message bodies, attachments, threads, drafts and draft attachments, send and reply, message search, inbox events, metrics, and list entries — reads and writes. **Why this rather than the source** A real inbox an agent owns, rather than an SMTP credential it borrows from a human. **It is also a door to the rest** The same login reaches 26 sources and 580+ operations. Find the contact elsewhere in the catalogue, then write to them from here — without adding a second server. **What it costs** Finding and inspecting an operation is free. Running one is billed per call at API prices, with no seat and no monthly minimum, and every call takes max_price_usd so an agent cannot overspend by accident. **Where else it reaches** https://mcp.aisa.one/sales/mcp finds the person to write to.
Hosted email MCP for AI agents with inboxes, send/receive, memory, recovery, and credits.
