netease-mail-mcp

163 邮箱 MCP 服务 —— 通过 Model Context Protocol 将邮箱功能接入 AI 助手

---

概述

netease-mail-mcp 是一个标准的 Model Context Protocol (MCP) 服务，将 163 邮箱的收发、搜索、管理能力暴露给兼容 MCP 协议的 AI 助手（如 WorkBuddy、Claude Desktop 等）。

通过 IMAP（收件）和 SMTP（发件）协议连接 163 邮箱服务器，提供 10 个标准化工具，覆盖日常邮件处理的全部场景。

核心能力

功能	工具	说明
邮件列表	mail_list	分页列出邮件，支持未读筛选
邮件详情	mail_get	获取完整邮件内容（正文+附件信息）
发送邮件	mail_send	发送新邮件，支持 CC/BCC
回复邮件	mail_reply	回复邮件，自动维护邮件线索
搜索邮件	mail_search	按关键词/发件人/日期搜索
标记已读	mail_mark_read	批量标记已读
文件夹	mail_list_folders	列出所有文件夹及统计
下载附件	mail_download_attachment	下载邮件附件（Base64）
删除邮件	mail_delete	移入垃圾箱
移动邮件	mail_move	移动邮件到其他文件夹

---

快速开始

前置条件

• Python 3.10+
• 163 邮箱账号
• 客户端授权码（非登录密码）

方式一：pipx 安装（推荐）

# 安装 pipx（如已安装可跳过）
brew install pipx        # macOS
# 或 pip install pipx    # 通用

# 安装 netease-mail-mcp
pipx install netease-mail-mcp

方式二：pip 安装

pip install netease-mail-mcp

macOS 用户如遇到 externally-managed-environment 错误，请使用方式一（pipx）。

方式三：源码开发

git clone https://github.com/wecoreai/netease-mail-mcp.git
cd netease-mail-mcp
pip install -e .

配置

创建配置文件（推荐放 ~/.netease-mail-mcp/config.yaml）：

mail:
  account: "your_email@163.com"
  auth_code: "your_auth_code_here"
  name: "你的昵称"

imap:
  server: "imap.163.com"
  port: 993

smtp:
  server: "smtp.163.com"
  port: 465

测试运行

# pipx / pip 安装（自动找到配置文件）
netease-mail-mcp

# 源码模式
python -m netease_mail_mcp.server

接入 WorkBuddy

编辑 ~/.workbuddy/mcp.json：

pipx / pip 安装模式：

先用 which netease-mail-mcp 获取可执行文件路径，然后配置：

{
  "mcpServers": {
    "netease-mail": {
      "command": "/Users/admin/.local/bin/netease-mail-mcp",
      "args": [],
      "cwd": "/Users/admin/.netease-mail-mcp"
    }
  }
}

源码开发模式：

{
  "mcpServers": {
    "netease-mail": {
      "command": "python",
      "args": ["-m", "netease_mail_mcp.server"],
      "cwd": "/absolute/path/to/netease-mail-mcp"
    }
  }
}

字段说明：command = 可执行程序绝对路径；args = pipx 模式留空 []，源码填 ["-m", "..."]；cwd = config.yaml 所在目录。

更详细的配置说明（含 Claude Desktop、Docker、环境变量传授权码）见 部署指南。

---

使用指南

接入 WorkBuddy 后，用自然语言就能操控邮箱，不需要记工具名、不用写代码。

查邮件

你说	效果
「看看收件箱」	列出最新 20 封
「搜一下华为发来的邮件」	按关键词搜索
「打开第 3 封」	查看完整正文
「看看未读邮件」	只列未读的

发邮件

你说	效果
「给 xxx@163.com 发封邮件，主题会议确认，正文周三下午3点见」	发送
「回复第 5 封，就说收到，明天详谈」	自动加 Re: 前缀
「抄送给 xxx@qq.com，密送给他老板」	发送时带 CC/BCC

管邮件

你说	效果
「把招行的每日信用管家全删了」	批量搜索并删除
「这几封标为已读」	批量标记
「移到归档文件夹」	移动分类
「下载那封邮件的附件」	下载附件

10 个工具速查

工具	用途	常见触发词
mail_list	列邮件	看看收件箱、有没有新邮件
mail_get	看详情	打开、看看内容、第 X 封
mail_search	搜索	搜一下、找一找
mail_send	发邮件	发邮件、写一封信
mail_reply	回复	回复、回他
mail_mark_read	标已读	标为已读
mail_list_folders	文件夹	有哪些文件夹
mail_download_attachment	下载附件	下载附件
mail_delete	删邮件	删除、清掉
mail_move	移动	移到、归档

💡 核心原则：你说人话，AI 干活。 不需要记工具名，不需要写代码，一句话搞定。

更详细的场景示例见 使用指南。

---

项目结构

netease-mail-mcp/
├── README.md                    # 项目概览
├── pyproject.toml               # Python 项目配置
├── requirements.txt             # 依赖清单
├── config.yaml.example          # 配置模板
├── .gitignore                   # Git 忽略规则
├── docs/
│   ├── API.md                   # 工具 API 详细文档
│   ├── ARCHITECTURE.md          # 架构设计文档
│   └── DEPLOYMENT.md            # 部署指南
├── src/
│   └── netease_mail_mcp/
│       ├── __init__.py          # 包元信息
│       ├── server.py            # MCP Server 入口（工具注册+路由）
│       ├── config.py            # 配置管理（YAML 加载+校验+环境变量覆盖）
│       ├── imap_client.py       # IMAP 客户端（收件核心）
│       ├── smtp_client.py       # SMTP 客户端（发件核心）
│       ├── email_parser.py      # 邮件解析器（RFC822 → 结构化数据）
│       └── models.py            # 数据模型（EmailMessage/Attachment/MailFolder）
└── tests/
    └── __init__.py

---

技术栈

层级	技术	说明
协议	MCP (Model Context Protocol)	AI 助手与工具的通信标准
传输	stdio (JSON-RPC 2.0)	标准输入输出流
邮件协议	IMAP4 (SSL)	收件、搜索、文件夹管理
邮件协议	SMTP (SSL)	发件、回复
配置	YAML + 环境变量	双优先级配置
Python 标准库	imaplib, smtplib, email, ssl, asyncio	零第三方依赖的邮件处理

---

安全说明

• 授权码存储在 config.yaml 中，该文件已加入 .gitignore
• 建议使用环境变量 MAIL_AUTH_CODE 覆盖敏感信息（生产环境推荐）
• 所有网络通信使用 SSL/TLS 加密（IMAP:993, SMTP:465）
• MCP Server 仅在本机 stdio 通道运行，不暴露网络端口

---

许可

MIT License © 2026 微核智算科技有限公司