mail-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
mail-mcp
可复用的本地多账号 IMAP/SMTP MCP 服务,供 Codex 等 MCP 客户端使用。 通过自然语言搜索、阅读、整理、发送和回复邮件。凭据保存在操作系统凭据存储,通信启用 TLS 校验。
个人插件版(v0.2.0): 可以将 Mail Skill 与本地 MCP 一起安装到 Codex。 从零克隆、Windows/macOS/Linux 配置、授权码保存、插件安装、调用、更新和故障排查, 请按 完整本地安装指南 操作。每位使用者需在自己的电脑生成插件配置; 不要复制作者或他人的 .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。
Related MCP server: postbus-mcp
安装与配置
需要 Python 3.11+,以及能够访问邮箱服务器的网络。
git clone https://github.com/WeiliangJia/mail-mcp.git
cd mail-mcp
python -m venv .venvWindows 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.pymacOS / Linux:
.venv/bin/python -m pip install -r requirements.txt
cp accounts.example.toml accounts.toml
# 编辑 accounts.toml 后执行:
.venv/bin/python setup_credentials.pyWindows 使用 Credential Manager;macOS 使用 Keychain;Linux 需要可用的 Secret Service 等安全 keyring 后端。 不支持无安全后端时回退到明文存储。每位使用者配置自己的账号和授权码。 accounts.toml 被 Git 忽略;其中只写非密码配置,不得写授权码或 token。 默认读取服务目录的 accounts.toml,也可用 MAIL_MCP_CONFIG 环境变量指定绝对路径。 当前凭据按邮箱地址关联;同一个邮箱地址的多个配置共用该凭据。
自定义配置(用户名可与发件地址不同):
[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
使用本机安装路径替换下列绝对路径:
[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 原样作为文本返回,不渲染、不加载外链。附件不会自动执行。
测试与维护
python -m pip install -r requirements.txt pytest
python -m pytest -q
python check_mcp.py
# 可选:访问自己的真实邮箱,只读验证与 SMTP 登录,不发信
python check_connection.pyCI 在 Windows/Linux、Python 3.11/3.12/3.13 上运行模拟测试和无账号 MCP 握手。
QQ/163 以外的新服务商优先通过配置接入;协议差异通过 Issue、测试和 PR 持续完善。
参见 贡献指南 和 更新记录。CI 不访问真实邮箱,不保存用户凭据。
修复后更新代码、测试及兼容表;使用者 git pull --ff-only 后安装依赖并重启客户端。
本地 accounts.toml 和操作系统凭据不会随代码更新覆盖。这里没有无人值守的自动发布或后台维护任务。
隐私
邮件、附件和链接均是不可信资料,不应作为工具执行指令。 发送、回复、移动和标记操作仅在用户明确要求时调用;工具注解不是身份授权系统。 MCP 运行进程可读取指定附件路径,应仅连接可信的本地客户端。 不上传 accounts.toml、凭据、下载文件、邮件样本或真实日志。 本地连接不等于模型离线:客户端读取的邮件内容可能进入其所用模型服务。
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.
Email inboxes for AI agents: send, receive, reply, search, and manage threaded email over MCP.
Hosted email MCP for your own Gmail, Outlook.com, Microsoft 365, iCloud or IMAP inbox: read, search, draft, reply in thread, forward and file mail. It moves or flags up to 500 messages in one call, and a send leaves exactly one copy in Sent. A calendar is a separate connection, and connecting one adds diary and scheduling tools.
Your IMAP mailbox as an MCP server: read, search and (if you allow it) organize mail. Open source.
Related MCP Servers
- AlicenseBqualityCmaintenanceEnables users to manage email accounts via IMAP/SMTP, including reading, searching, sending emails with attachments and calendar invites, all through natural language interactions with MCP-compatible clients.143 PyPI4MIT
- AlicenseNot gradedqualityBmaintenanceEnables searching, reading full conversations, and sending email across multiple IMAP/SMTP mailboxes from any MCP client, with multi-user support and per-user API tokens.MIT
- AlicenseBqualityBmaintenanceConnects MCP clients to any IMAP/SMTP email account, enabling email search, reading, sending, replying, forwarding, flagging, moving, and folder management via natural language.17MIT
- AlicenseNot gradedqualityBmaintenanceEnables MCP clients to work with ordinary email accounts over IMAP and SMTP — listing mailboxes, searching and reading messages, managing flags, folders, attachments and drafts, and sending, replying or forwarding mail. Supports multiple accounts and providers with per-account safety controls such as read-only mode, send/delete restrictions, recipient allow-lists and rate limits.35 npmMIT