Skip to main content
Glama
mail-mcp

mail-mcp

by WeiliangJia

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 .venv

Windows 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:

.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 环境变量指定绝对路径。 当前凭据按邮箱地址关联;同一个邮箱地址的多个配置共用该凭据。

自定义配置(用户名可与发件地址不同):

[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.py

CI 在 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…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      Enables 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.
      1
      43 PyPI
      4
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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
    • A
      license
      B
      quality
      B
      maintenance
      Connects MCP clients to any IMAP/SMTP email account, enabling email search, reading, sending, replying, forwarding, flagging, moving, and folder management via natural language.
      17
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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 npm
      MIT