Problem: AI agents have no native email access.
Why: IMAP+SMTP are universal, server-agnostic, and require no OAuth2 dance.
How: FastMCP tools layer, pure stdlib SMTP, imapclient for IMAP, secrets via bw-env.

mail_mcp/
├── config.yaml          # Non-sensitive settings (hosts, ports, env var names)
├── config.py            # @lru_cache loader + 3-tier secret resolution
│
├── 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
└── cli.py               # Typer+Rich admin: serve, status, inbox, folders, accounts

1. Process env     → fastest (already injected by shell or MCP host)
2. bw-env login    → zsh -l -c 'printf "%s" "${VAR}"'  (Bitwarden GLOBAL_ENV_VARS)
3. local .env      → dev override only, never committed

# Install (editable)
uv tool install --editable .

# Check credentials
mail-mcp status

# List folders
mail-mcp folders

# Show inbox
mail-mcp inbox -n 5

# Start MCP server
mail-mcp serve

"mail-mcp": {
  "command": "zsh",
  "args": ["-l", "-c", "/home/kpihx/.local/bin/mail-mcp serve"]
}

[mcp_servers.mail_mcp]
command = "zsh"
args = ["-l", "-c", "/home/kpihx/.local/bin/mail-mcp serve"]