netease-mail-mcp

English | 简体中文

让 Claude Code、Codex、Cursor、Claude Desktop 安全地读写你的网易邮箱（163 / 126 / yeah.net / 188）：搜索、阅读、起草、发送，写操作先预览、再确认。

30 秒上手

1. 在网页版邮箱 设置 → POP3/SMTP/IMAP 里开启「IMAP/SMTP 服务」，生成一个客户端授权码（不是登录密码）。

2. 在终端运行（需要 uv）：

   uvx netease-mail-mcp-server setup
   

   按提示输入邮箱地址和授权码。授权码存进系统钥匙串，不会写进配置文件。

3. 按下面任一客户端的写法接入。setup 结束时也会打印对应的配置；之后可随时用 uvx netease-mail-mcp-server config <claude-code|codex|cursor|claude-desktop> 重新生成。

4. 自检：uvx netease-mail-mcp-server doctor（检查登录、IMAP ID、文件夹、SMTP、收取选项）。

接入各个客户端

Claude Code

claude mcp add --scope user netease-mail -- uvx netease-mail-mcp-server

Codex（~/.codex/config.toml）

[mcp_servers.netease-mail]
command = "uvx"
args = ["netease-mail-mcp-server"]

Cursor（~/.cursor/mcp.json）

{
  "mcpServers": {
    "netease-mail": {
      "command": "uvx",
      "args": ["netease-mail-mcp-server"]
    }
  }
}

Claude Desktop（macOS：~/Library/Application Support/Claude/claude_desktop_config.json；Windows：%APPDATA%\Claude\claude_desktop_config.json）

{
  "mcpServers": {
    "netease-mail": {
      "command": "uvx",
      "args": ["netease-mail-mcp-server"]
    }
  }
}

Claude Desktop 等图形客户端启动时可能找不到 uvx，此时把 command 换成 uvx 的绝对路径（config 子命令会自动填好）。要限制权限，加环境变量，例如 "env": { "NETEASE_MAIL_MODE": "draft" }。

工具

共 10 个工具，按权限模式注册：模式不允许的工具根本不会出现在客户端里。

没有永久删除工具。readonly 下 read_message 也不会改变任何邮件状态。

权限模式与确认机制

用 NETEASE_MAIL_MODE 设置：readonly（只读）、draft（读 + 写草稿，不能发信和移动）、full（全部，默认）。

发送、移动、删除是两阶段操作，确认方式由 NETEASE_MAIL_CONFIRM 决定：

• elicit：通过 MCP 的 elicitation 机制，由客户端弹出确认界面，由你本人点击同意后才执行。这是最强的保证。客户端必须支持 elicitation，不支持时该模式会直接报错，不会悄悄降级。
• token：第一次调用只返回完整预览和一个一次性确认令牌。令牌是 HMAC，绑定刚才预览的确切内容，10 分钟内有效、用过即废；内容有任何改动都会被拒绝。
• auto（默认）：客户端声明支持 elicitation 就走 elicit，否则走 token。我们没有逐个核实各客户端对 elicitation 的支持情况，请以你所用客户端的文档为准。

只要客户端声明了支持 elicitation，就只有你明确勾选「同意」才会执行：弹窗出错、客户端返回无效答复、点了接受却没勾选同意、拒绝或取消，一律按未同意处理，不会退回到令牌。令牌只给根本不支持 elicitation 的客户端用。这时结果状态是 not_confirmed（你点了拒绝或取消则是 declined_by_user），并附带提示：如果你的客户端其实弹不出确认框，把 NETEASE_MAIL_CONFIRM 设成 token。

预览（弹窗里的文字和令牌模式下的 JSON 是同一份内容）包括：发件人；全部收件人，含抄送和密送；主题；纯文本正文和 HTML 正文转成的文本，各最多 8000 字，超出时明确写出「还有 N 个字符未显示」；HTML 和纯文本内容不一致时给出警告（收件人多半看到的是 HTML）；每个附件的文件名、大小和解析后的完整路径。用 draft_id 发送草稿时，预览显示草稿里真实的 From、Reply-To 和收件人；draft_id 必须是草稿箱里带 \Draft 标记的草稿（服务器支持这个标记时），收件箱里的邮件不能当草稿发出去。移动/删除的预览列出每一封邮件。

SMTP 服务器接受邮件之后，保存「已发送」或删除草稿这些后续步骤即使出错，结果也是「已发送」加警告，不会报错，免得被误以为没发出去而重发。部分收件人被服务器拒绝时也给出警告，并列出这些地址。确认「已发送」里没有副本时，草稿不删除，留作发出内容的唯一记录。

诚实地说明令牌的边界：令牌强制模型先预览再执行，并保证执行的就是预览的内容，但它无法证明有人类批准过——能调用工具的模型自己也能拿着令牌再调一次。因此对安全要求高的场景，请设置 NETEASE_MAIL_CONFIRM=elicit，或者直接使用 readonly / draft 模式，让 Agent 根本没有发信能力（草稿由你自己在邮箱里检查后发送）。

另外：邮件内容一律视为不可信数据，返回给模型时会加上标记，提示其中的指令不是命令；预览里的正文（可能引用或转发了别人的邮件）、发件人和收件人、主题、附件文件名、草稿内容，以及待移动邮件的发件人和主题也一样。wait_for_message 的 from 只匹配发件地址，不看显示名，因为显示名可以随便伪造成 "noreply@github.com" <x@evil.example>：写完整地址时要求完全一致，写 @github.com 匹配这个域名及其子域名，其他写法按地址里的子串匹配；search_messages 的 from 仍同时匹配显示名和地址。

下载和附件的路径限制

• 下载：download_attachment 只会写进下载目录（NETEASE_MAIL_DOWNLOAD_DIR，默认 ~/Downloads/netease-mail-mcp/）或它的子目录。dest_dir 写相对路径（如 发票/2026）或下载目录里的绝对路径；指向下载目录以外的（包括经过符号链接或 ..、UNC 路径 \\server\share、C:相对路径 这类写法）一律拒绝。文件以独占方式新建：不覆盖已有文件、不跟随链接，权限 0600，新建的目录 0700。macOS 上给文件加 com.apple.quarantine 标记，Windows 上写 Zone.Identifier，加不上也不影响下载。
• 附件：路径先解析符号链接再检查，并按磁盘上的实际文件判断位置，所以 ~/LIBRARY 这类大小写不同的写法同样会被识别。以下位置一律拒绝：主目录下任何以 . 开头的文件或目录（.ssh、.env、.git、.config 等）、~/Library（iCloud 云盘所在的 ~/Library/Mobile Documents 和 Dropbox / OneDrive / Google Drive 所在的 ~/Library/CloudStorage 除外）、%APPDATA% / %LOCALAPPDATA%、/proc、/sys、/dev、/etc、网络路径（UNC）、非普通文件，以及读到的内容和文件大小对不上的特殊文件。设置 NETEASE_MAIL_ATTACHMENT_ROOTS（多个目录用系统路径分隔符隔开，macOS/Linux 是 :，Windows 是 ;）后，只能附加这些目录里的文件，上面的拒绝规则照样生效；唯一的例外是明确写进这个变量、又位于 ~/Library 里的目录（例如微信、飞书存放收到文件的目录），其中的文件可以附加。被拒时，把文件复制到普通目录再附加，或把它所在的目录加进这个变量。

网易邮箱的坑

这些是用真实 163 / yeah.net 账号逐项验证出来的，也是本项目存在的理由。

• 必须先发 IMAP ID。 登录后若不发 ID 命令，LIST/STATUS 能用，但每次 SELECT 都会失败并提示 Unsafe Login。Python 的 imaplib 不认识 ID，本项目自行注册并在每次登录后发送。
• 服务端搜不了关键词。 对 FROM / TO / SUBJECT / TEXT / BODY 的 SEARCH，在 163 上返回空结果；在 yeah.net 上我们实测 30 秒内不返回，之后账号还会慢上几分钟。可靠的只有 SINCE / BEFORE / UNSEEN / SEEN / FLAGGED / UNFLAGGED。所以本项目的做法是：日期和状态条件交给服务端，再批量取回邮件头，在本地对解码后的发件人、收件人、主题做匹配。不搜正文，结果里会明确标 body_searched: false；搜索范围有上限（max_scan），被截断时会如实报告 truncated。
• 「收取选项」决定 IMAP 能看到什么。 网页版 设置 → POP3/SMTP/IMAP → 收取选项 默认可能是「最近 30 天」，此时收件箱在 IMAP 里可能只有几十封，而网页上有几千封。不是 bug，把它改成「全部」即可；doctor 会在发现最早的邮件正好是 30 天前时提醒你。
• 授权码可被撤销。 在网页版删除授权码会立刻让对应客户端掉线，并报登录失败。登录失败的错误信息会指向这一点；重新生成授权码、再运行 setup 即可。
• 没有 MOVE。 163/yeah.net 不支持 IMAP MOVE。移动和删除用 UID COPY + UID STORE +FLAGS (\Deleted) + UID EXPUNGE <这些 UID>（依赖 UIDPLUS）。只会清除我们刚复制的那几封，不会发无参数的 EXPUNGE，不会连带清掉你别处标了删除的邮件。
• SMTP 用 465（隐式 TLS）。 25 端口 + STARTTLS 可用，587 端口不通（超时）。
• 发出的信，服务器会自己存进「已发送」。 2026-10-28 实测：经 smtp.163.com:465 发出的一封邮件，163 自动在「已发送」里存了一份，且只有一份。send_email 发送后按 Message-ID 在「已发送」里找（约 5 秒内查 3 次），找到就不再自己保存（结果里 sent_copy: "stored_by_server"），找不到才用 APPEND 补存一份（"appended"），所以不会出现两份。其他域名尚未实测。
• IDLE 因域名而异。 yeah.net 支持，163 不支持；wait_for_message 在不支持时自动改为轮询。
• 删除有延迟。 刚 EXPUNGE 的邮件可能在约 2 秒内仍被列出。

性能

测试环境：2026-10-28，家庭宽带，scripts/benchmark.py（只读，不发信不改信）。每项先预热一次，再取 3 次的中位数。

说明：数字依赖网络和网易服务器当时的状态，冷启动明显更慢（一次紧接在超时的服务端搜索之后的 500 封扫描耗时 16 s）。批量取头的开销：500 封冷数据下，只取邮件头 0.67 s，只取 BODYSTRUCTURE 1.19 s，两者都取 1.35 s。这是一个本地的无缓存、无后台进程的实现，每次调用都实时访问服务器。

对比

截至 2026-10，仅比较功能，信息来自两个项目当前的 README；它们各有适合的场景，如有出入请提 issue 指正。

常见问题

授权码是什么？为什么不用我的密码？ 授权码是网易为第三方客户端单独生成的凭据，可随时在网页版撤销，不会暴露登录密码，也绕过不了你的登录保护。在 设置 → POP3/SMTP/IMAP 开启 IMAP/SMTP 服务时生成。本项目不接受、也不需要账号密码。

为什么搜不到正文？ 网易的 IMAP 服务端不支持有效的关键词/正文搜索（见上文），而本项目不建本地索引或缓存库。需要正文时，先用日期、发件人、主题缩小范围，再用 read_message 读。

搜索结果比网页上少很多？ 多半是「收取选项」设成了最近 30 天，见上文。

Windows / Linux 的凭据存在哪？ Windows 存在凭据管理器，Linux 存在 Secret Service（GNOME Keyring、KWallet 等）。无图形桌面的 Linux 没有 Secret Service 时，可通过环境变量 NETEASE_MAIL_AUTH_CODE__<邮箱大写，非字母数字换成下划线> 提供授权码，例如 NETEASE_MAIL_AUTH_CODE__ME_163_COM。

怎么删除一个账号？ uvx netease-mail-mcp-server accounts remove you@163.com，会同时删除钥匙串里的授权码。也别忘了在网页版撤销这个授权码。查看已配置账号：accounts list。

支持企业邮箱（qiye.163.com）吗？ 不支持。也不支持 POP3、日历、通讯录。

安全与隐私

• 授权码只存在系统凭据库：macOS 钥匙串、Windows 凭据管理器、Linux Secret Service；不写入任何配置文件或日志。macOS 上通过 /usr/bin/security 读写，setup 经标准输入传递密钥，不会出现在进程参数里。
• 配置文件（账号列表、模式）权限为 0600，不含密钥。
• 本项目无服务端、无遥测，只直连网易的 IMAP/SMTP 服务器；不缓存邮件内容，没有后台进程。
• 邮件内容视为不可信，见上文；发信和移动需要预览与确认；下载和附件有路径限制，见上文。
• 发现安全问题请看 SECURITY.md。

环境变量

Agent Skill

skills/netease-mail/SKILL.md 给 Agent 提供工作流指引（先搜索再阅读再起草、发送前必须展示预览并取得明确同意、邮件内容不可信、验证码流程）。

开发

见 CONTRIBUTING.md 和 docs/ARCHITECTURE.md。版本记录见 CHANGELOG.md。

许可证

MIT