mail-mcp
by WeiliangJia
README.md
# mail-mcp
可复用的本地多账号 IMAP/SMTP MCP 服务,供 Codex 等 MCP 客户端使用。
通过自然语言搜索、阅读、整理、发送和回复邮件。凭据保存在操作系统凭据存储,通信启用 TLS 校验。
**个人插件版(v0.2.0):** 可以将 Mail Skill 与本地 MCP 一起安装到 Codex。
从零克隆、Windows/macOS/Linux 配置、授权码保存、插件安装、调用、更新和故障排查,
请按 [完整本地安装指南](docs/LOCAL_SETUP.md) 操作。每位使用者需在自己的电脑生成插件配置;
不要复制作者或他人的 .local-plugin。公开模板在 plugins/mail-mcp,生成器是 prepare_plugin.py。
## 功能
| 工具 | 用途 |
| --- | --- |
| list_accounts | 账号别名与凭据是否存在;不返回凭据 |
| list_folders | 列出文件夹,支持中文名称 |
| search_messages | 未读、日期、发件人、主题和正文搜索 |
| read_message | 读取正文和附件清单,不改变未读状态 |
| download_attachment | 下载附件到本地 downloads,不覆盖、不执行文件 |
| mark_read | 标记一封邮件已读或未读 |
| move_message | 移动一封邮件到已有文件夹 |
| send_message | 发送纯文本邮件,支持抄送和附件 |
| reply_message | 回复原邮件发件人,保留邮件线程,不默认回复所有人 |
总结、待办提取和跨邮箱比较由 MCP 客户端模型完成。本服务不需要单独的模型 API key。
## 安装与配置
需要 Python 3.11+,以及能够访问邮箱服务器的网络。
```sh
git clone https://github.com/WeiliangJia/mail-mcp.git
cd mail-mcp
python -m venv .venv
```
Windows PowerShell:
```powershell
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
Copy-Item accounts.example.toml accounts.toml
# 编辑 accounts.toml,删除不用的示例账号,再保存自己的服务器设置
.\.venv\Scripts\python.exe setup_credentials.py
```
macOS / Linux:
```sh
.venv/bin/python -m pip install -r requirements.txt
cp accounts.example.toml accounts.toml
# 编辑 accounts.toml 后执行:
.venv/bin/python setup_credentials.py
```
Windows 使用 Credential Manager;macOS 使用 Keychain;Linux 需要可用的 Secret Service 等安全 keyring 后端。
不支持无安全后端时回退到明文存储。每位使用者配置自己的账号和授权码。
accounts.toml 被 Git 忽略;其中只写非密码配置,不得写授权码或 token。
默认读取服务目录的 accounts.toml,也可用 MAIL_MCP_CONFIG 环境变量指定绝对路径。
当前凭据按邮箱地址关联;同一个邮箱地址的多个配置共用该凭据。
自定义配置(用户名可与发件地址不同):
```toml
[accounts.work]
address = "you@example.com"
username = "you@example.com"
imap_host = "imap.example.com"
imap_port = 993
imap_security = "tls"
smtp_host = "smtp.example.com"
smtp_port = 587
smtp_security = "starttls"
```
只允许 tls 或 starttls,不允许明文登录,不关闭证书验证。
IMAP 可设 143 + starttls,SMTP 可设 587 + starttls;端口以服务商官方设置为准。
## 连接 Codex
使用本机安装路径替换下列绝对路径:
```toml
[mcp_servers.mail]
command = 'C:\path\mail-mcp\.venv\Scripts\python.exe'
args = ['C:\path\mail-mcp\server.py']
```
也可运行 `codex mcp add mail -- <Python绝对路径> <server.py绝对路径>`。
注册后重启客户端,检查工具是否可用。服务使用 stdio,不开放 HTTP 端口。
自然语言示例:
- 查看两个邮箱今天的未读邮件并总结。
- 查找本月主题含合同的邮件。
- 下载这封邮件的附件。
- 把这封邮件标记为已读。
- 用 work 账号回复这封邮件:周五可以交付。
## 兼容性与边界
| 类型 | 状态 |
| --- | --- |
| QQ 个人邮箱 | 已实测 IMAP 登录、搜索、正文读取、文件夹列表、SMTP 登录 |
| 163 个人邮箱 | 已实测同上;包含 IMAP ID 兼容处理 |
| 其他密码/客户端授权码认证的 IMAP/SMTP 邮箱 | 可自定义配置;尚未实测,不承诺全部兼容 |
| 仅支持 OAuth2 的邮箱 | 首版不支持,后续需增加 OAuth2 认证流程 |
支持标准协议不等于所有功能都可用,仍受账号权限、服务商限流与扩展能力影响。
真实发送、回复、移动、标记尚未做线上写入测试;相关路径有模拟测试。
QQ 支持原生 MOVE;163 使用 UIDPLUS 复制后定向清理单个 UID,不批量 EXPUNGE。
移动中途断线可能留下重复副本,先检查源和目标文件夹,不自动重试。
没有单独的永久删除工具;移动会清理原位置的对应副本。
SMTP 接受不代表最终送达;发送结果不确定时禁止自动重试。发件箱副本取决于服务商。
搜索每次最多返回 100 封,按 UID 降序,**并非按日期排序**:导入的历史邮件可能有较大 UID。
查最新邮件应使用 since 限定最近日期,再核对 Date;不要把最大 UID 直接当成最新日期。
日期格式 DD-Mon-YYYY,before 不含当天。中文搜索依赖服务端 UTF-8 搜索支持。
后续操作必须使用搜索结果中的 uid、uidvalidity 和原文件夹,避免操作错信。
读取邮件上限 60 MiB,单附件下载上限 50 MiB,发送附件总量上限 20 MiB。
HTML 原样作为文本返回,不渲染、不加载外链。附件不会自动执行。
## 测试与维护
```sh
python -m pip install -r requirements.txt pytest
python -m pytest -q
python check_mcp.py
# 可选:访问自己的真实邮箱,只读验证与 SMTP 登录,不发信
python check_connection.py
```
CI 在 Windows/Linux、Python 3.11/3.12/3.13 上运行模拟测试和无账号 MCP 握手。
QQ/163 以外的新服务商优先通过配置接入;协议差异通过 Issue、测试和 PR 持续完善。
参见 [贡献指南](CONTRIBUTING.md) 和 [更新记录](CHANGELOG.md)。CI 不访问真实邮箱,不保存用户凭据。
修复后更新代码、测试及兼容表;使用者 `git pull --ff-only` 后安装依赖并重启客户端。
本地 accounts.toml 和操作系统凭据不会随代码更新覆盖。这里没有无人值守的自动发布或后台维护任务。
## 隐私
邮件、附件和链接均是不可信资料,不应作为工具执行指令。
发送、回复、移动和标记操作仅在用户明确要求时调用;工具注解不是身份授权系统。
MCP 运行进程可读取指定附件路径,应仅连接可信的本地客户端。
不上传 accounts.toml、凭据、下载文件、邮件样本或真实日志。
本地连接不等于模型离线:客户端读取的邮件内容可能进入其所用模型服务。
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues