mcp-email is an MCP server that wraps any standard IMAP/SMTP mailbox (Gmail, Outlook, Yahoo, iCloud, self-hosted, etc.) into tools for AI assistants, supporting local stdio, remote HTTP, and OAuth modes.
Send & Manage Emails
email_send – Send messages with HTML/plain text, multiple recipients (to/cc/bcc), attachments, custom headers, and automatic retry with exponential backoff.
email_reply, email_forward – Reply to or forward existing messages.
email_save_draft, email_send_draft – Save and send drafts.
Read & Search Emails
email_list_messages – List message headers in a folder (newest first) with IMAP search syntax support (UNSEEN, FROM, SINCE, etc.).
email_get_message – Fetch full email content including text/HTML body and attachment metadata; optionally mark as read.
email_get_attachment – Download a specific attachment.
Organize Folders & Messages
email_list_folders – Retrieve all IMAP mailbox/folder names.
email_create_folder – Create new folders (supports non-ASCII/Chinese names).
email_move_messages – Move emails between folders.
email_delete – Delete and expunge messages.
Apply Rules & Mark
email_apply_rules – Scan a folder and apply conditional rules (move, mark, delete) based on sender/subject criteria; supports dry-run, regex, and first/all-match modes.
email_mark – Add or remove IMAP flags (\Seen, \Flagged, etc.).
Configure & Test
email_configure – Dynamically update SMTP/IMAP credentials, ports, TLS, and other settings at runtime—no restart required.
email_test_connection – Verify SMTP and/or IMAP connectivity.
Prompts (Slash Commands): triage_inbox, weekly_cleanup, draft_reply.
Remote Deployment: HTTP mode (Basic auth, multi-user, no stored credentials) and OAuth mode (stateless encrypted tokens, suitable for claude.ai connectors).
Allows sending and receiving emails via a self-hosted Dovecot IMAP server and associated SMTP server, supporting attachments, flags, folder management, and rule-based automation.
Allows sending and receiving emails via Gmail's IMAP and SMTP servers, supporting attachments, flags, folder management, and rule-based automation.
Allows sending and receiving emails via iCloud Mail's IMAP and SMTP servers, supporting attachments, flags, folder management, and rule-based automation.
Allows sending and receiving emails via Zoho Mail's IMAP and SMTP servers, supporting attachments, flags, folder management, and rule-based automation.
Click on "Install 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., "@mcp-email send an email to john@example.com with subject 'Meeting' and body 'See you tomorrow.'"
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.
純 Python 實作（mcp_email.py），把任意支援 IMAP / SMTP 的標準信箱（Gmail / Outlook / Yahoo / iCloud / Zoho / 公司 Exchange / 自架 mail server …）包成 MCP tools 給 Claude / Claude Code / Cowork / 任何 MCP host 用。
三種啟動模式（參考 m2k-calendar-tools 的部署架構）：
模式 | 指令 | 適用場景 | 認證 |
stdio（預設） |
| 本機單人（Claude Desktop / Code） | 環境變數 / |
HTTP |
| 內網多人共用（Claude Code / Desktop 遠端連線） | 每請求 |
OAuth |
| claude.ai Connectors（手機 app / 網頁版） | OAuth 2.1 + 無狀態加密 token，伺服器不存帳密 |
Tool | 用途 |
| Runtime 動態切換 SMTP / IMAP 帳密、port、TLS、附件上限、收件人白名單 |
| 一鍵測 SMTP + IMAP 是否能登入 |
| 寄信：HTML + 純文字、to/cc/bcc、檔案/Base64 附件、Reply-To、自訂 headers、retry |
| 回覆某封信：自動帶 |
| 轉寄某封信： |
| IMAP 列出所有 mailbox 名稱（中文名稱自動解碼） |
| 列出 folder 內訊息 header（支援 IMAP search syntax；含 |
| 抓單封信完整內容（body text/html、附件 metadata 含 index、 |
| 下載單封信裡某個附件的實際內容（base64），以 filename 或 index 指定；有大小上限保護 |
| 加/移除 IMAP flag（ |
| 標記 |
| 建立 folder（支援中文，自動 modified UTF-7；已存在不報錯） |
| 搬信：UID MOVE，server 不支援則 COPY + UID EXPUNGE fallback |
| 規則整理：掃描後依條件 move/mark/delete， |
| 把一封信存成草稿（IMAP APPEND 到草稿匣， |
| 把草稿匣裡的某封草稿寄出，成功後從草稿匣刪除 |
Prompt | 用途 |
| 分流信箱：列未讀 → 摘要 → 建議動作（參數：folder、limit） |
| 每週整理：引導 |
| 讀取指定信件並草擬回覆、確認後才寄（參數：uid、folder、tone） |
對應使用者需求：
📤 寄信 HTML + 純文字 ✅（multipart/alternative，純文字 fallback 自動）
👥 多收件人 to / cc / bcc ✅（bcc 不會 出現在 header）
📎 附件 — 本機檔案路徑 + Base64 ✅（text/* 自動 charset=utf-8）
🔧 Runtime 動態設定 ✅（email_configure tool，任一欄位可單獨更新）
🔍 連線測試 ✅（SMTP NOOP + IMAP NOOP 各別測）
⚡ 高效能 ✅（timeout 可調、SMTP send 失敗 exponential backoff 重試）
Related MCP server: mail-mcp
⚠️ 尚未發佈到 PyPI（首次發佈流程見文末〈發佈到 PyPI〉）。發佈後即可用 下列方式安裝；在那之前請用下一節「從原始碼」。
發佈後，用 uv 免手動建環境，首次執行自動抓套件：
uvx mcp-email # 直接跑（uv 會自動安裝到隔離環境）
# 或
pipx install mcp-email
pip install mcp-email # 裝進現有環境，提供 `mcp-email` 指令MCP host 設定（Claude Desktop / Code / Cursor / Cline … 通用），帳密走 env：
{
"mcpServers": {
"email": {
"command": "uvx",
"args": ["mcp-email"],
"env": {
"IMAP_SERVER": "imap.gmail.com", "IMAP_PORT": "993",
"SMTP_SERVER": "smtp.gmail.com", "SMTP_PORT": "465", "SMTP_USE_SSL": "true",
"EMAIL_USER": "you@gmail.com", "EMAIL_PASS": "<app password>"
}
}
}
}Claude Code 使用者：repo 內附
.mcp.json，用claude開這個資料夾會自動提示啟用。
建議用獨立的 virtualenv，避免污染系統 Python（也不要把 .venv/ 提交到 git）：
cd ~/Documents/workspace/mcp-email
# 建立並啟用虛擬環境（請用你實際的 Python，例如 Homebrew 的 python3）
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
# 執行時依賴
pip install -r requirements.txt
# 開發 / 測試依賴（含 aiosmtpd 假 SMTP）
pip install -r requirements-dev.txt
# 跑端到端測試（in-process 假 SMTP + 假 IMAP）
python test_e2e.py
# 預期：=== 49/49 passed ===
# 遠端（--http/--oauth）模式測試
python -m pytest test_remote.py -q⚠️ macOS 注意：別用
/usr/bin/python3（CommandLineTools 內建的 stub）建 venv， 它可能跳出xcode-select安裝提示。請改用 Homebrew 的python3（/opt/homebrew/bin/python3）或 pyenv。.venv/已列入.gitignore， 不會、也不該進版控；clone 後請各自重建。
打開 Claude 的 MCP 設定檔（通常在 ~/Library/Application Support/Claude/claude_desktop_config.json 或對應路徑），加上：
{
"mcpServers": {
"email": {
"command": "python3",
"args": ["/Users/weiting/Documents/workspace/mcp-email/mcp_email.py"],
"env": {
"SMTP_HOST": "smtp.gmail.com",
"SMTP_PORT": "587",
"SMTP_USER": "you@gmail.com",
"SMTP_PASS": "<gmail app password>",
"SMTP_USE_TLS": "true",
"IMAP_HOST": "imap.gmail.com",
"IMAP_PORT": "993",
"IMAP_USER": "you@gmail.com",
"IMAP_PASS": "<gmail app password>",
"IMAP_USE_SSL": "true",
"EMAIL_FROM": "Your Name <you@gmail.com>",
"EMAIL_TIMEOUT_SEC": "30",
"EMAIL_RETRY_MAX": "3"
}
}
}
}重啟 Claude 後就會看到 email_* 系列 tool 出現。
不設環境變數也可以，啟動後第一次用之前先呼叫 email_configure 設定帳密（runtime 設定不會落地，重啟會清空）。
如果你的帳密放在 ~/.secrets（會被 shell source 的機密檔），可以用附帶的 run_server.sh：
它會先 source ~/.secrets 再啟動 server，所以連 GUI 啟動的 Claude Desktop 也吃得到 env、
而設定檔裡完全不用寫密碼。設定改成：
{
"mcpServers": {
"email": { "command": "/絕對路徑/mcp-email/run_server.sh" }
}
}環境變數別名：server 同時接受兩種命名，~/.secrets 不必改名 —
標準名 | 也接受的別名 |
|
|
|
|
|
|
帳密只需設一組：SMTP 與 IMAP 通常是同一個信箱帳號，所以帳密不必重複設 —
用共用的 EMAIL_USER / EMAIL_PASS（或 MAIL_*），SMTP / IMAP 兩邊都吃；
或只設一邊（例如只有 IMAP_USERNAME / IMAP_PASSWORD），另一邊會自動沿用同一組帳密。
只有 host / port 因協定不同需各自設（如 smtp.x.com:587 vs imap.x.com:993；自架常是同 host 不同 port）。
只設一個協定也可以：IMAP 與 SMTP 功能完全獨立 —— 只設 IMAP 就能用全部讀信工具
（list_folders / list_messages / get_message / mark / delete）；
只設 SMTP 就能用 email_send。要兩種都用才需要兩邊的 host 都設。
以下兩種模式讓同一份 server 部署在內網主機 / NAS / 雲端 VM，多人共用。
共同原則：伺服器只設定主機資訊（IMAP_HOST / SMTP_HOST / port / TLS），
不設定任何人的帳密；每位使用者的帳密隨請求帶入、原樣 pass-through 給
IMAP/SMTP 登入，撤銷 = 使用者自己改密碼或撤掉應用程式專用密碼。
兩種模式都是明文帳密等級的傳輸，正式部署必須放在 HTTPS 反向代理後面
（nginx / Caddy / Synology 反向代理皆可）。放在反向代理後面時，記得設
EMAIL_ALLOWED_HOSTS=你的對外網域，否則 SDK 的 DNS-rebinding 防護會把
請求擋成 421 Invalid Host header。
遠端模式與 stdio 的行為差異（多人共用的安全考量）：
email_configure 停用並自 tool 列表隱藏（全域設定不容任一使用者改動）
path 附件預設停用（那是「伺服器」的檔案系統）；請改用 content_base64，
或由管理員設 EMAIL_ATTACHMENT_DIRS 白名單開放
預設 From = 該請求登入的帳號（不吃伺服器端 EMAIL_FROM）
# 已安裝（pip / pipx）或直接 uvx，一行起服務：
IMAP_HOST=mail.example.com SMTP_HOST=mail.example.com \
uvx mcp-email --http --host 0.0.0.0 --port 8765
# 從原始碼跑也一樣：python3 mcp_email.py --http --host 0.0.0.0 --port 8765主機設定也可以放在工作目錄的 .env 檔（KEY=VALUE 每行一組，環境變數優先），
不必每次打在指令前。
每位使用者在自己的 Claude Code 註冊（帳密只存在自己機器上）：
claude mcp add --transport http email https://主機/mcp \
--header "Authorization: Basic $(printf '%s' '帳號:密碼' | base64)"伺服器不保存任何帳密、也絕不回退到環境變數憑證：沒帶 Authorization
標頭的工具呼叫一律被拒絕。
注意：OAuth 模式為單行程設計（進行中的授權交易存在記憶體）， 不支援多副本負載平衡；token 本身無狀態，重啟不影響已發 token。
claude.ai 的連線來自 Anthropic 雲端，issuer 必須是公網可達的 HTTPS 網址：
# uvx（自動帶上 OAuth 模式的額外依賴 cryptography）：
IMAP_HOST=mail.example.com SMTP_HOST=mail.example.com \
uvx --with cryptography mcp-email --oauth --issuer https://mail-mcp.example.com \
--host 0.0.0.0 --port 8765
# 或既有環境：pip install "mcp-email[oauth]"（= pip install cryptography）流程：標準 OAuth 2.1（動態註冊 + PKCE）。使用者第一次連接會被導到
/login 輸入信箱帳密（建議應用程式專用密碼），bridge 先以 IMAP 登入驗證，
通過後把憑證用伺服器金鑰 AES-GCM 加密封進 token —— 無狀態設計，
伺服器沒有憑證資料庫。access token 1 小時、refresh token 30 天自動輪替。
claude.ai 端：設定 → 連接器（Connectors）→ 新增自訂連接器 → 貼上
https://mail-mcp.example.com/mcp。
相關環境變數（皆選配）：
變數 | 用途 |
| token 加密金鑰（urlsafe base64 的 32 bytes）；沒設就自動產生 |
| 金鑰檔 / DCR client 註冊檔路徑（Docker 部署指向 |
| 設了之後，登入帳號沒打 |
| 登入失敗日誌（固定格式，供 fail2ban 監看封鎖來源） |
| 反向代理後的對外網域白名單（逗號分隔） |
⚠️ 金鑰是整個 OAuth 模式的單點要害：拿到 bridge 金鑰的人可以解開所有
已發 token 內的使用者憑證。金鑰檔 / EMAIL_BRIDGE_KEY 務必限縮讀取權限、
不進版控（repo 的 .gitignore 已排除 .bridge-key），有疑慮就換金鑰
（代價只是所有人重新授權一次）。
內建防護：登入頁同意畫面（顯示發起授權的應用程式名稱＋授權碼送達的 網域，讓使用者辨識並攔截釣魚連結）、登入失敗節流（同 IP / 全域滑動視窗， 避免上游信箱服務封鎖 bridge 的 IP）、同授權交易密碼錯誤 5 次作廢、 登入頁安全標頭、auth log 自我輪替。搭配 fail2ban 的 filter 範例：
# /etc/fail2ban/filter.d/mcp-email.conf
[Definition]
failregex = mcp-email-login-fail ip=<HOST>
# jail：logpath 指向 EMAIL_AUTH_LOG 的路徑，maxretry/bantime 視需求現成多架構 image（linux/amd64 + linux/arm64，打 v* tag 由 GitHub Actions 自動發佈）：
# GHCR（免登入即可 pull）
docker pull ghcr.io/weiting-tw/mcp-email:latest
# Docker Hub（維護者設定 DOCKERHUB_* secret 後才會發佈）
docker pull weiting-tw/mcp-email:latest或自己建：
docker build -t mcp-email .
# HTTP 模式（把 mcp-email 換成上面的 image 名稱亦可）
docker run -d -p 8765:8765 \
-e IMAP_HOST=mail.example.com -e SMTP_HOST=mail.example.com \
mcp-email
# OAuth 模式（掛 /data volume 保留金鑰與 client 註冊）
docker run -d -p 8765:8765 -v mcp-email-data:/data \
-e IMAP_HOST=mail.example.com -e SMTP_HOST=mail.example.com \
mcp-email --oauth --issuer https://對外網址 --host 0.0.0.0 --port 8765容器以非 root（uid 10001）執行。OAuth 模式為單行程設計（授權交易存在 記憶體），不支援多副本負載平衡。
mail-mcp.example.com {
reverse_proxy 127.0.0.1:8765
}nginx 使用者：proxy_pass http://127.0.0.1:8765; 並保留
proxy_set_header Host $host;；SSE 緩衝不用另外關（server 回應已帶
X-Accel-Buffering: no）。設好代理後記得配 EMAIL_ALLOWED_HOSTS=mail-mcp.example.com。
上線 --http / --oauth 前逐項確認，尤其打 ✅ 的三項是實務上最常害人踩雷的：
HTTPS 反向代理：帳密/token 是明文等級傳輸，一定要放在 TLS 後面，絕不裸跑對外。
EMAIL_ALLOWED_HOSTS：設成你的對外網域，否則 SDK 的 DNS-rebinding 防護會回 421 Invalid Host header。
✅ OAuth 金鑰要持久化：--oauth 一定要掛 -v mcp-email-data:/data（或設固定的 EMAIL_BRIDGE_KEY）。沒掛 volume→容器每次重啟都重新產生金鑰→所有人 token 全失效、要重新授權，這是最常見的災情。
✅ 金鑰檔權限：.bridge-key（或 /data）只給執行帳號讀；拿到金鑰的人可解開所有已發 token 內的使用者憑證。已在 .gitignore 排除，切勿進版控。
✅ 用應用程式專用密碼：宣導使用者在登入頁輸入 App Password，不要用信箱主密碼——外洩時只波及收發信、可單獨撤銷。
同意畫面：登入頁會顯示「哪個應用程式要連你的信箱」＋「授權碼送達的網域」；提醒使用者只在認得目的地時才繼續（防釣魚）。
失敗節流 / fail2ban：設 EMAIL_AUTH_LOG 並掛 fail2ban（filter 範例見上），擋帳密暴力猜測。
path 附件：遠端模式預設停用；若確有需求才用 EMAIL_ATTACHMENT_DIRS 白名單開放，範圍越小越好。
token 生命週期已知：access 1 小時（自動續）、refresh 30 天（活躍使用者滾動不過期）；使用者改密碼＝所有舊 token 失效（需重新授權），這是刻意的撤銷機制。
服務 | SMTP host | port | TLS | IMAP host | port | SSL | 備註 |
Gmail |
| 587 | TLS |
| 993 | SSL | |
Outlook / Microsoft 365 |
| 587 | TLS |
| 993 | SSL | 帳號需開 SMTP / IMAP 開關 |
Outlook.com / Hotmail |
| 587 | TLS |
| 993 | SSL | 同上 |
Yahoo Mail |
| 587 | TLS |
| 993 | SSL | 需開 App Password |
iCloud Mail |
| 587 | TLS |
| 993 | SSL | 需開 App-specific Password |
Zoho Mail |
| 587 | TLS |
| 993 | SSL | |
自架（Postfix + Dovecot） | 視設定 | 587/465 | TLS / SSL | 視設定 | 143/993 | STARTTLS / SSL |
安全提醒：別把純密碼塞進 config 檔案明文。建議：
Gmail / Yahoo / iCloud / Outlook：用 App Password（兩階段驗證 → 應用程式密碼）
公司 Exchange：問 IT 拿 SMTP/IMAP credential，或用 OAuth（這個版本暫未支援 OAuth flow）
密碼存 macOS Keychain 並用 security find-generic-password -w 動態注入
TLS / SSL 憑證驗證：預設兩邊都 驗 憑證（verify_cert: true）。自架信箱或公司內部用自簽憑證會在連線時 CERTIFICATE_VERIFY_FAILED 報錯。要關掉驗證：
// 環境變數
"SMTP_VERIFY_CERT": "false",
"IMAP_VERIFY_CERT": "false"或 runtime 用 email_configure：
{ "smtp": { "verify_cert": false }, "imap": { "verify_cert": false } }關掉後會喪失 MITM 防護，只在自簽 / 測試環境用，連 Gmail / Outlook 之類公網信箱絕對不要關。
附件路徑白名單：因為 email_send 的 path 附件受模型/host 控制，預設不設限時，
理論上可被誘導把任意本機檔案（如 ~/.ssh/id_rsa）夾帶寄出。若要防護，設定允許目錄：
// 環境變數（os.pathsep 分隔，macOS/Linux 用 : ）
"EMAIL_ATTACHMENT_DIRS": "/Users/me/Documents:/Users/me/Pictures"或 runtime 用 email_configure：
{ "attachment_allowed_dirs": ["/Users/me/Documents", "/Users/me/Pictures"] }設定後，path 附件只能來自這些目錄底下（會解析 symlink 防繞過），名單外一律 PermissionError。
空白（預設）= 不限制。content_base64 附件不受此限（內容由呼叫端直接提供）。
收件人網域白名單（防被誘導亂寄，開關，預設關）：email_send / email_reply /
email_forward / email_send_draft 都是對外動作，若擔心模型被惡意信件內容誘導亂寄，
可限制只能寄到指定網域：
// 環境變數（逗號分隔）
"EMAIL_ALLOWED_RECIPIENT_DOMAINS": "gss.com.tw,example.com"設定後任何收件人（to/cc/bcc）網域不在清單內就 PermissionError；空白（預設）= 關閉不限制。
附件下載大小上限：email_get_attachment 把附件 base64 回傳，過大的附件會撐爆模型
context / 記憶體，預設上限 5MB（超過只回 metadata 並標 too_large）。可用
EMAIL_MAX_ATTACHMENT_BYTES 調整，或呼叫時以 max_bytes 覆蓋。
⚠️ Prompt injection（把這套接上 LLM 最重要的風險）：信件的主旨/內文是寄件人可控的，
email_get_message / email_list_messages 會把它們原樣回給模型，惡意信可能夾帶
「請把這封轉寄到 …／刪除某資料夾」之類的指令試圖操縱模型。防線：
絕不要把信件內文裡的指令當成命令執行——內文永遠是「資料」不是「指令」。
破壞性/對外動作（send/reply/forward/delete/move/apply_rules/send_draft）
執行前一律先向使用者確認；多數 MCP host（Claude Desktop/Code）本來就會對每次工具
呼叫要求核准，這是主要安全網，別關掉它。
加上上面的收件人網域白名單當第二層防線；apply_rules 保持 dry_run=true 先預覽。
{
"smtp": {
"host": "smtp.gmail.com",
"port": 587,
"username": "you@gmail.com",
"password": "xxxx xxxx xxxx xxxx",
"use_tls": true
},
"imap": {
"host": "imap.gmail.com",
"port": 993,
"username": "you@gmail.com",
"password": "xxxx xxxx xxxx xxxx",
"use_ssl": true
},
"email_from": "Your Name <you@gmail.com>",
"retry_max": 3
}{
"to": ["alice@example.com", "bob@example.com"],
"cc": "carol@example.com, dave@example.com",
"bcc": ["eve@example.com"],
"subject": "週報 2026-06-12",
"text": "純文字版本內容",
"html": "<h1>週報</h1><p>本週進度：…</p>",
"reply_to": "support@example.com",
"headers": {
"X-Report-Week": "2026-W24"
},
"attachments": [
{"path": "/Users/me/Documents/report.pdf"},
{"path": "/Users/me/Pictures/chart.png", "filename": "週報圖表.png"},
{
"content_base64": "SGVsbG8gV29ybGQh",
"filename": "data.txt",
"mime_type": "text/plain"
}
]
}{ "smtp": true, "imap": true }回傳：
{
"smtp": {"ok": true, "host": "smtp.gmail.com", "port": 587},
"imap": {"ok": true, "host": "imap.gmail.com", "port": 993}
}{
"folder": "INBOX",
"limit": 20,
"search": "UNSEEN"
}IMAP search syntax 常用：
ALL、UNSEEN、SEEN、FLAGGED、UNFLAGGED、ANSWERED、UNANSWERED、DELETED、DRAFT、RECENT
FROM "alice@example.com"、TO "..."、CC "..."、SUBJECT "週報"
SINCE 1-Jan-2026、BEFORE 31-Dec-2026、ON 12-Jun-2026
邏輯：UNSEEN FROM "alice"、OR FROM "alice" FROM "bob"、NOT SEEN
中文關鍵字：支援。非 ASCII 關鍵字會自動改用 SEARCH CHARSET UTF-8 + literal
（RFC 3501 標準做法）；一次一個中文詞，且含 OR/NOT 時要放在最後一個條件。
若伺服器接受語法但比對不到（實測 Mail2000 不解 RFC2047 編碼的中文標頭），會自動
fallback 成「以剩餘 ASCII 條件縮小範圍 → 抓 header 在客戶端比對」（掃描上限 200 封，
回傳會附 note 說明）。email_apply_rules 的規則比對本來就在客戶端做，中文不受限。
{ "folder": "INBOX", "uid": "12345", "mark_read": false }{"folder": "INBOX", "uids": ["12345", "12346"], "flag": "\\Seen", "add": true}
{"folder": "INBOX", "uids": ["12345"]}=== 49/49 passed ===另有 test_mcp_stdio.py：用真正的 MCP client 把 mcp_email.py 以 stdio 子行程啟動，
跑完整 initialize → list_tools → 呼叫 tool 的 handshake，驗證能被任何 MCP host 載入。
以及 test_remote.py（40 tests）：遠端模式的 Basic 標頭解析、每請求憑證覆蓋、
遠端限制（email_configure / path 附件停用、白名單 symlink 繞過）、
OAuth token 加解密與 provider 流程（含失敗節流、狀態清理、DCR 上限淘汰）、
in-process uvicorn 起真正 streamable-http server 的端對端測試——包括
「HTTP Basic 帳密穿透到 IMAP/SMTP 登入」與「DCR→PKCE→/login→token→Bearer
呼叫工具」的完整 OAuth 授權流程。
每次 push / PR 會由 GitHub Actions 在 Python 3.10–3.13 上自動跑兩支測試（見 .github/workflows/test.yml）。
涵蓋三類情境：
SMTP 寄信（in-process aiosmtpd 假 SMTP，真的把信送過去比對）
header（From / To / Cc / Reply-To / Subject）
bcc 不外漏（rcpt_tos 有 bcc 但 header 沒）
multipart：純文字 + HTML 兩個 part 都存在
附件：檔案 + base64 兩種來源，filename 含中文（備註.txt）也對
retry：port 沒人 listen 時 SMTP 會 raise ConnectionRefusedError
密碼不會出現在 email_configure 回傳
錯誤路徑 / 安全
沒寄件人、沒收件人、附件不存在、壞 base64 各自 raise 對應 error
html-only 自動補純文字 fallback
附件白名單：名單外檔案被 PermissionError 擋下、名單內正常附加
IMAP 讀信（FakeIMAP 取代真連線）
list_folders / list_messages（UID 正確解析）/ get_message（text+html+附件 metadata）
mark（flag 真的寫入）/ delete（UID EXPUNGE，及不支援 UIDPLUS 時 fallback）/ test_connection（IMAP NOOP）
parser 健壯性：FLAGS/UID 出現在 BODY literal「之後」的回應排序也能正確解析
無 OAuth flow：目前只支援帳密。Gmail / 365 OAuth2 比較複雜，要看後續是否真實需要再加。
不維護長連線：每次 IMAP 呼叫都重開連線。簡單可靠，效能上對「偶爾讀信」場景夠用；如果你要做「常駐 polling」可能要改長連線。
IMAP search 直接傳給伺服器：自由度高但要懂 RFC 3501 syntax；含空格的字串記得加雙引號（如 FROM "alice@x.com"）。
刪信用 UID EXPUNGE：email_delete 在 server 支援 UIDPLUS（RFC 4315）時只清掉你指定的 uid，不會誤刪資料夾內其他已標 \Deleted 的信；不支援時才 fallback 到一般 EXPUNGE（回傳的 method 欄位會標明用了哪種）。
附件大小：受 SMTP 伺服器限制（Gmail 25MB、Outlook 20MB、Exchange 視設定）。本工具不設上限，超過會直接 SMTP error。
遠端模式的多帳號：--http / --oauth 天生多人（每請求帶各自憑證、彼此隔離）；stdio 模式仍是一個 instance 一個帳號，多帳號要靠 host 多開幾個 instance（每個給不同 env）。
OAuth 模式單行程：授權交易存在記憶體，不支援多副本負載平衡；token 本身無狀態，重啟不影響已發 token（金鑰不變的前提下）。
推 v* tag 會由 GitHub Actions 自動 build + 發佈（.github/workflows/publish.yml，
走 PyPI Trusted Publishing，不需要 API token）：
# 1. bump pyproject.toml 的 version 並 commit
# 2. 上 tag 並推出去，Actions 就會發佈
git tag v0.3.0 && git push origin v0.3.0一次性設定：PyPI 的 mcp-email 專案 → Settings → Publishing → 新增 GitHub publisher
（owner weiting-tw、repository mcp-email、workflow publish.yml、environment pypi），
並在 GitHub repo 的 Settings → Environments 建立名為 pypi 的 environment。
MIT。隨便用。
掃描 folder 後，依規則對信件做 move / mark / delete。預設：子字串、大小寫不敏感、first-match-wins（一封信只套第一條命中的規則）。可用 case_sensitive / match_mode 與每條規則的 match(substring|regex|exact) 調整。強烈建議先 dry_run=true 預覽命中數與前幾封，確認無誤再執行。
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| rules | Yes | ||
| folder | No | INBOX | |
| search | No | 可選 IMAP search 先在 server 端縮小掃描範圍（大信箱建議用） | ALL |
| dry_run | No | ||
| match_mode | No | first=一封只套第一條命中規則；all=套用所有命中規則（執行優先序 move>delete>mark） | first |
| case_sensitive | No | 比對是否區分大小寫（預設否） |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description effectively discloses key behavioral traits: defaults (substring, case-insensitive, first-match-wins), adjustable parameters (match_mode, case_sensitive), action precedence for 'all' mode, and the safety recommendation of dry_run. It does not mention rate limits or auth requirements, but covers the core operational behavior well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise paragraph that front-loads the purpose and then provides defaults, options, and a safety recommendation. Every sentence contributes useful information, though it could be slightly restructured for improved readability (e.g., bullet points for defaults).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 parameters, rule-based logic) and no output schema, the description covers core functionality and recommendations but omits the return value/response format and details on error handling or the 'search' parameter usage. Some important context is missing for fully autonomous selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 43%. The description adds context beyond the schema by explaining the default matching logic and the effect of match_mode and case_sensitive. However, it does not elaborate on all parameters (e.g., limit, folder, search) beyond what is in the schema, providing only moderate added value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool scans a folder and applies rules to move, mark, or delete emails, with specific default behaviors (substring, case-insensitive, first-match-wins). It differentiates from sibling tools like email_mark, email_delete, and email_move_messages by focusing on batch rule application.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides usage guidance by strongly recommending dry_run=true for safety and explains default matching behavior. It does not explicitly state when to use this tool versus alternative sibling tools for individual actions, but the context of rule-based batch operations is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Runtime 動態設定 SMTP / IMAP 帳號設定。任一欄位可單獨更新，未提供的欄位維持現值。回傳更新後的非敏感設定摘要。
| Name | Required | Description | Default |
|---|---|---|---|
| imap | No | ||
| smtp | No | ||
| retry_max | No | ||
| email_from | No | 預設寄件人 | |
| retry_base_delay | No | ||
| attachment_allowed_dirs | No | 附件路徑白名單目錄。設定後 email_send 的 path 附件只能來自這些目錄底下，用來防止任意本機檔案外洩。空 list 代表不限制。 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description mentions fields can be updated individually and unprovided fields retain current value, which is helpful. However, with no annotations, it fails to disclose permissions, potential impact on connections, or error handling. The return of non-sensitive settings is noted but not detailed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences efficiently convey the core function, incremental update behavior, and return value. It is front-loaded with the main purpose, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of nested objects and absence of output schema, the description lacks detail on error conditions, side effects, or the specific format of the returned summary. It is insufficient for an agent to reliably use the tool without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33%, and the description does not compensate by explaining individual parameter meanings. It only states that any field can be updated, leaving the agent to infer parameter purpose from the schema, which is incomplete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool configures SMTP/IMAP account settings at runtime with the ability to update individual fields. It uses specific verb and resource, and the purpose is distinct from sibling tools which focus on email operations like sending, listing, or moving messages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives or when not to use it. The context is implied but not stated, missing exclusion criteria or comparative context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
建立 IMAP folder / mailbox（支援中文名稱，自動 modified UTF-7 編碼）。已存在時不報錯，回傳 already_exists=true。
| Name | Required | Description | Default |
|---|---|---|---|
| folder | Yes | 資料夾名稱，如 'BizForm Testing' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses key behaviors: supports Chinese names with automatic modified UTF-7 encoding, does not error on existing folders, and returns already_exists=true. This provides clear expectations for the agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences convey all necessary information without redundancy. Critical details (encoding, duplicate handling) are front-loaded and precise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple create tool with one parameter and no output schema, the description covers core aspects: creation behavior, encoding, and duplicate handling. It adequately informs without overspecifying.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with a description for the 'folder' parameter, but the description adds meaning beyond the schema by mentioning Chinese name support and encoding transformation, which clarifies acceptable inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool creates an IMAP folder/mailbox, with specific details about Chinese name support and automatic encoding. It distinguishes itself from sibling tools like email_list_folders and email_delete by focusing solely on creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for creating folders but lacks explicit guidance on when to use this tool versus alternatives like email_list_folders to check existing folders. No when-not-to-use or alternative names are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
標記 \Deleted 並 expunge。注意：無法復原。
| Name | Required | Description | Default |
|---|---|---|---|
| uids | Yes | ||
| folder | No | INBOX |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the two-step process (mark + expunge) and warns that the action cannot be undone. However, it omits behavioral details like permission requirements, impact on other folders, or whether it works on all IMAP servers. With no annotations, more depth is expected.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: two sentences, front-loaded with the action. No unnecessary words. However, the use of Chinese may reduce clarity for some agents, and the brevity sacrifices useful context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, low schema coverage, and two parameters, the description is incomplete. It does not explain the return value, behavior when uids are invalid, or how expunge affects the folder. The note about irreversibility helps but is insufficient for full understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds no information about parameters. 'uids' and 'folder' are not explained; the agent must rely solely on the schema, which has 0% description coverage. The meaning of 'uids' (message UIDs) and the role of 'folder' are left unclarified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: mark as \Deleted and expunge, which effectively permanently deletes emails. It distinguishes itself from siblings like email_mark (which only marks) and email_move_messages (which moves to trash). The note about irreversibility reinforces the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like email_mark or email_move_messages. Does not specify prerequisites, such as whether the emails must already be marked as deleted or if the folder parameter is required. The agent lacks context for appropriate selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
抓取單封郵件完整內容（含 body text/html、附件 metadata）。預設 peek 不改 SEEN flag。
| Name | Required | Description | Default |
|---|---|---|---|
| uid | Yes | ||
| folder | No | INBOX | |
| mark_read | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions that by default, fetching does not change the SEEN flag, which is useful. However, it does not disclose other behaviors like permissions, rate limits, or what happens when mark_read is true.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise, consisting of a single sentence. It front-loads the main purpose, but the structure could be improved by separating the behavioral note from the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (3 params, no output schema), the description covers the main purpose and a key behavior. However, it lacks details on return format and parameter specifics, leaving some incompleteness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description should compensate by explaining parameters. The description only covers the default behavior but does not explain the meaning or expected values for uid, folder, or mark_read.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches complete content of a single email, including body and attachment metadata. This specific verb+resource combination effectively distinguishes it from sibling tools like email_list_messages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide guidance on when to use this tool versus alternatives, nor does it mention prerequisites or exclusions. It only notes the default peek behavior, leaving the agent without explicit usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
列出 IMAP 上所有 mailbox / folder 名稱。
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states it lists all names, but does not disclose whether the list is hierarchical, sorted, or includes any special folders. The behavior is partially transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. It is concise and front-loaded with the key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks details about the return format or any behavioral nuances. Since there is no output schema, more information about what is returned (e.g., flat list or hierarchy) would be helpful. It is minimally adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters, and schema coverage is 100%. The description does not need to add meaning beyond the schema since there are no parameters. It is adequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb '列出' (list) and the resource 'IMAP 上所有 mailbox / folder 名稱' (all mailbox/folder names on IMAP). It distinguishes itself from sibling tools like email_create_folder and email_delete, which have different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit guidance on when to use this tool versus alternatives. The usage is implied by the action of listing folders, but there are no when-not or alternative suggestions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
列出指定 folder 中的訊息 header（最新優先）。可用 IMAP search syntax 篩選（預設 ALL）。
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| folder | No | INBOX | |
| search | No | IMAP search 條件，如 UNSEEN / FROM "xxx@y.com" / SINCE 1-Jan-2026 | ALL |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses it lists headers (not full content) and defaults to ALL search, but omits authentication needs, rate limits, or error scenarios.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise with two sentences. Front-loaded with purpose. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given three parameters, no output schema, and no annotations, the description is adequate for a simple list tool but lacks detail on pagination, header content, error handling, or performance characteristics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 33% (only search has a schema description). The tool description adds minimal parameter context beyond mentioning IMAP search; limit and folder are not elaborated. It partially compensates but insufficiently for the low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists message headers in a specified folder, with newest first, and mentions IMAP search filtering. This distinguishes it from siblings like email_get_message (full message) and email_delete (destructive).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It does not explicitly state when to use this tool vs alternatives (e.g., for full messages use email_get_message). The search syntax hint is useful but no exclusions or prerequisites are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
加 / 移除 IMAP flag（\Seen / \Flagged 等）。
| Name | Required | Description | Default |
|---|---|---|---|
| add | No | ||
| flag | Yes | \Seen | |
| uids | Yes | ||
| folder | No | INBOX |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility. It only states add/remove flags but does not disclose behavioral details like idempotency, permanence, permissions needed, or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, directly states purpose with no wasted words. However, it is too brief to be effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 4 parameters, no output schema, and no annotations, the description is insufficient. It lacks information on return values, error handling, and full behavioral scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description adds minimal value. It mentions flag examples but does not explain the 'add' boolean, 'uids' array, or 'folder' parameter. The description fails to compensate for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (add/remove) and resource (IMAP flag) with examples. It distinguishes from sibling tools which handle other email operations like applying rules or sending messages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. There is no mention of prerequisites, limitations, or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
把指定 UID 的信從 source_folder 搬到 destination_folder。優先用 UID MOVE，server 不支援則 fallback 為 COPY + UID EXPUNGE。目的地需先存在（請先呼叫 email_create_folder）。
| Name | Required | Description | Default |
|---|---|---|---|
| uids | Yes | ||
| source_folder | Yes | ||
| destination_folder | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description explains the key behavioral aspect: preference for UID MOVE and fallback to COPY+UID EXPUNGE. It also specifies the data moved (messages by UID). However, it doesn't disclose error handling, authorization needs, or what happens if some UIDs fail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary action, and each sentence adds essential information (purpose, fallback, precondition). No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple move tool with three string parameters and no output schema, the description covers the main operation, fallback behavior, and a key precondition. It could mention error conditions or UID validity, but overall it provides sufficient context for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description indirectly defines each parameter: uids are the message identifiers, source_folder is the origin, destination_folder is the target. It adds the constraint that destination must exist. While not detailing format or constraints, it provides enough context for a straightforward tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool moves messages with specified UIDs from source_folder to destination_folder, using UID MOVE with fallback. It distinguishes itself from sibling tools like email_list_messages or email_create_folder by specifying the move action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit precondition that the destination folder must exist and refers to email_create_folder for that purpose. It also explains the fallback behavior, providing context on when it might behave differently. However, it doesn't explicitly contrast with other tools for copying or other operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
寄送郵件。支援 HTML + 純文字、to/cc/bcc 多收件人、檔案/Base64 附件、自訂 headers、Reply-To。失敗自動 retry（exponential backoff）。
| Name | Required | Description | Default |
|---|---|---|---|
| cc | No | ||
| to | Yes | 收件人，可逗號分隔字串或 list | |
| bcc | No | ||
| from | No | 覆蓋預設 From | |
| html | No | HTML 內容 | |
| text | No | 純文字內容 | |
| headers | No | ||
| subject | Yes | ||
| reply_to | No | ||
| attachments | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It mentions automatic retry with exponential backoff, but lacks details on success/failure responses, rate limits, or authentication requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences efficiently convey the main function and key features, then a second sentence adds retry behavior. No wasted words, though could be slightly more structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 10 parameters, nested objects, and no output schema, the description covers core features but omits details like the 'from' override, required 'subject' parameter, or how attachments are handled. Adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 40%; the description adds context by listing supported features (HTML, plain text, to/cc/bcc, attachments, headers, Reply-To), mapping to several parameters. However, it does not explain parameter formats or constraints beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states '寄送郵件' (send email) and lists supported features, making the tool's purpose unambiguous. It is the only send tool among siblings, so differentiation is inherent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool over alternatives. While siblings have different functions, the description does not mention when not to use this tool or any prerequisites (e.g., authentication).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
測試 SMTP 與/或 IMAP 連線是否能登入。回傳兩邊狀態。
| Name | Required | Description | Default |
|---|---|---|---|
| imap | No | ||
| smtp | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description bears full responsibility. It only states it 'tests connections' and 'returns status', but does not disclose if connections are modified, credentials are stored, or side effects occur. The return format is undefined.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, each essential. First sentence states action, second states output. No redundancy, front-loaded with purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description must specify return format. It only says 'returns both sides' status' without detail. Parameters are simple, but missing output description makes it barely adequate for a test tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so description must compensate. It mentions 'SMTP and/or IMAP', implying the boolean parameters toggle these protocols. However, it does not explicitly map 'imap' and 'smtp' parameter names to their roles, leaving some ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool tests SMTP and/or IMAP connections and returns their status. It uses a specific verb-resource combination ('test connection') and distinguishes from sibling tools focused on email management like email_send or email_configure.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like email_configure. No prerequisites or conditions are mentioned. The description provides no 'when-to-use' or 'when-not-to-use' information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.2.0email_apply_rulesemail_configureemail_create_folderemail_deleteemail_get_messageemail_list_foldersemail_list_messagesemail_markemail_move_messagesemail_sendemail_test_connectionEach tool targets a distinct email operation (e.g., send, list, delete, apply rules) with no overlapping functionality. The descriptions clearly differentiate their purposes.
All tools follow a consistent 'email_verb_noun' pattern (e.g., email_get_message, email_list_folders). The naming is predictable and easy to navigate.
With 11 tools, the server covers core email workflows (send, receive, manage folders, rules) without being bloated or sparse. Each tool serves a clear purpose.
The tool set covers major email operations: send, list, get, delete, move, mark, manage folders, apply rules, configure, and test. Minor gaps like cross-folder search or attachment download are absent but not critical for typical usage.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Read, search, send, organize, draft and schedule email across your inboxes from any MCP client.
An MCP server that provides email capabilities, hosted on Alpic platform
An MCP server that provides email capabilities, hosted on Alpic platform
An MCP server that provides email capabilities, hosted on Alpic platform
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/weiting-tw/mcp-email'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
