Metadata-Version: 2.4
Name: netease-mail-mcp
Version: 1.0.0
Summary: 163 邮箱 MCP 服务 —— 通过 Model Context Protocol 接入邮箱，实现邮件接收、查看、搜索、回复、附件下载等全功能管理
Author-email: 微核智算科技有限公司 <support@wecoreai.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/wecoreai/netease-mail-mcp
Project-URL: Documentation, https://github.com/wecoreai/netease-mail-mcp/blob/main/docs/API.md
Keywords: mcp,email,netease,163,imap,smtp
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Email
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.0.0
Requires-Dist: PyYAML>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-mock>=3.14; extra == "dev"
Requires-Dist: pytest-cov>=6.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
Requires-Dist: ruff>=0.9; extra == "dev"
Requires-Dist: mypy>=1.14; extra == "dev"
Dynamic: license-file

# netease-mail-mcp

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

[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Version](https://img.shields.io/badge/version-1.0.0-orange.svg)](CHANGELOG.md)

---

## 概述

`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 邮箱账号
- [客户端授权码](https://help.mail.163.com/faqDetail.do?code=d7a5dc8471cd0c0e8b4b8f4f8e49998b)（非登录密码）

### 1. 安装

```bash
# 克隆项目
git clone https://github.com/wecoreai/netease-mail-mcp.git
cd netease-mail-mcp

# 安装依赖
pip install -r requirements.txt
```

### 2. 配置

```bash
# 复制配置文件模板
cp config.yaml.example config.yaml

# 编辑 config.yaml，填写你的邮箱和授权码
```

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

### 3. 测试运行

```bash
# 直接运行（stdio 模式）
python -m netease_mail_mcp.server
```

### 4. 接入 WorkBuddy

在 WorkBuddy 的 MCP 配置文件 `~/.workbuddy/mcp.json` 中添加：

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

更详细的配置说明见 [部署指南](docs/DEPLOYMENT.md)。

---

## 项目结构

```
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 微核智算科技有限公司
