email-mcp-lite
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| EMAIL_MCP_READONLY | No | Set to 1 for server-wide read-only mode: send/delete/move/mark are refused. | |
| EMAIL_MCP_CONFIG_DIR | No | Custom credential directory (default ~/.email-mcp) where accounts.json is stored. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
多账户邮件工具集（IMAP/SMTP）。首次使用：先调用 list_accounts；若显示尚未配置账户，引导用户在 email-mcp 项目目录运行 uv run email-mcp web 打开本地网页添加邮箱（或 uv run email-mcp add 交互录入），完成后立即生效、无需重启服务端。邮件 ID 形如 account|folder|uid，一律从 search_emails 的结果原样回传。send_email / delete_email 属于危险操作，建议用户在客户端开启人工确认。
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| list_accountsA | 列出已配置的邮件账户（id、登录用户、IMAP 服务器）。返回为空时说明尚未初始化，见返回值中的指引。 |
| list_foldersA | 列出账户的 IMAP 文件夹及邮件数/未读数，每行: 名称 (N封/M未读)。account 留空且仅一个账户时自动选择。 |
| search_emailsA | 搜索邮件，返回紧凑元数据（不含正文，省 token），每行: id | 日期 | 发件人 | 主题 [标记]。 field: subject/from/to/text(text=含正文全文检索，较慢); since/before: 'YYYY-MM-DD'; 空 query 且无日期 = 列出全部（新邮件在前）。 返回的 id 直接回传给 get_email/mark_email/move_email/delete_email/send_email。 |
| get_emailA | 读取邮件详情：头部 + 纯文本正文（默认截断 2000 字符）+ 附件清单（仅元数据）。 body_max=0 不取正文；想读全文可加大该值。id 来自 search_emails。 |
| get_attachmentsA | 把邮件附件保存到本地并返回路径列表（附件内容绝不内联进响应）。 attachment 留空=全部；可传序号（1 起）或文件名关键词。save_dir 留空默认 ~/Downloads/email-mcp/<账户>/。 |
| send_emailA | 发送邮件；draft=True 时改为存草稿不发信。 to/cc: 地址或 '名字 <a@b>'，多个用列表或逗号分隔。 回复: 传 in_reply_to=邮件id（自动设置引用头、收件人为原发件人，reply_all=True 时带上原抄送）。 转发: 传 forward_of=邮件id（自动引用原文；原附件不自动带上，可先 get_attachments 再经 attachments 发出）。 in_reply_to 与 forward_of 互斥。subject/body 留空时回复/转发场景自动补全。 |
| mark_emailB | 标记邮件：read=True 已读 / False 未读；starred=True 加星 / False 去星。至少传一个。 |
| move_emailB | 移动邮件到指定文件夹（归档=移到 Archive 类文件夹）。to_folder 名称来自 list_folders。 |
| delete_emailA | 删除邮件。默认软删除=移入回收站；permanent=True 彻底删除（不可恢复，建议客户端配置人工确认）。 注意：删除已在回收站里的邮件会直接彻底删除。 |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 9 tools
Each tool maps to a distinct resource+action: account listing, folder listing, metadata search, body retrieval, attachment download, sending, flagging, moving, and deleting. The potentially overlapping pairs (search_emails vs get_email, get_email vs get_attachments) are explicitly separated by token-saving metadata vs full body vs on-disk attachment saving.
Every tool follows a strict snake_case verb_noun pattern (list_accounts, list_folders, search_emails, get_email, get_attachments, send_email, mark_email, move_email, delete_email). The verbs are chosen from a small, predictable set.
Nine tools is well within the sweet spot and every tool earns its place for an email client surface. Nothing feels redundant or thin; even the two list_* tools cover genuinely different resources.
Core lifecycle is fully covered: discover accounts/folders, search and read mail, pull attachments, compose with draft/reply/forward, flag, move, and soft/hard delete. Minor gaps remain around folder management (create/rename/empty trash) and account initialization/configuration, but these are edge operations an agent can work around.