mail MCP

邮寄mcp

用于AI代理的通用IMAP+SMTP MCP服务器--v0.2.4

将任何电子邮件帐户连接到任何AI代理（Claude、Gemini、Codex、Copilot、Vibe……）。 意图优先设计：与真实用户工作流程相匹配的高级工具，由干净的IMAP/SMTP核心支持 和一个完整的 三重管理界面 （CLI+HTTP+电报）。

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.

回购协议 · GitLab

______________________________________________________________________

建筑

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

秘密解析（3层）

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)

______________________________________________________________________

运输

______________________________________________________________________

支持的帐户

更多帐户：在中添加条目 config.yaml --无需更改代码。

______________________________________________________________________

快速开始

# 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  
   # 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

______________________________________________________________________

管理界面

1.CLI-- mail-admin

mail-admin status [--account ]   # Rich table: env var, value (masked), source
mail-admin logs [N]                  # tail last N lines (default 40)
mail-admin credentials set   

mail-admin credentials unset 
mail-admin help                      # full capability map

2.HTTP路由

3.电报机器人

令牌环境： TELEGRAM_MAIL_HOMELAB_TOKEN --身份验证门： TELEGRAM_CHAT_IDS

4.SSH执行器

docker compose exec -T mail-mcp mail-admin status
docker compose logs --tail=100 mail-mcp

______________________________________________________________________

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"]
  }
}

______________________________________________________________________

工具参考

______________________________________________________________________

安全

• 凭据是 从不 存储在 config.yaml --只有环境变量名称。
• 秘密住在Bitwarden(GLOBAL_ENV_VARS)并通过以下方式注入 bw-env /登录shell。
• 管理员凭据覆盖持续存在 /data/mail-admin.env （Docker卷）——从未提交。
• 无OAuth2，无刷新令牌存储——仅通过TLS进行IMAP密码认证。

______________________________________________________________________

部署（Docker/homelab）

看 deploy/ 为了 docker-compose.yml 和 .env.example.

# Required env vars
X_LOGIN=your_imap_username
X_PASS=your_imap_password
TELEGRAM_MAIL_HOMELAB_TOKEN=    # optional
TELEGRAM_CHAT_IDS=    # optional
MAIL_MCP_ADMIN_ENV_FILE=/data/mail-admin.env

GitLab CI自动部署 master 通过以下方式发送给家庭实验室跑步者 docker compose up -d --build.