内容
# 邮件助手 MCP
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](https://github.com/jlowin/fastmcp)
[](https://github.com/psf/black)
基于 FastMCP 的邮件个人助手，为管理 Gmail 账户提供 MCP（模型上下文协议）工具。服务器暴露 stdio 和 SSE 传输协议，以便与 Claude Desktop 等兼容 MCP 的客户端集成。
## 功能特点
- **多账户 Gmail 支持**，通过 OAuth 2.0 和刷新令牌
- **基于规则的邮件自动化** - 创建、管理并应用规则以实现自动邮件分类
- **批量操作** - 高效移动多封邮件（比单个移动快 50-100 倍）
- **集成工作流** - `manage` 工具在一次调用中结合消息、规则和文件夹
- **多种传输协议** - stdio（用于 IDE）和 SSE（用于 Web 客户端）
- **全面日志记录** - 可配置的文件日志记录，支持敏感数据隐藏
## 前置条件
- [uv](https://docs.astral.sh/uv/) - 处理虚拟环境和依赖管理
- Python 3.11+ - 由 `uv sync` 自动安装
## 快速开始
### 1. 安装依赖
```bash
uv sync
```
### 2. 配置 Gmail 账户
设置 OAuth 凭证并进行身份验证（详见 [Google 控制台配置指南](Documentation/GOOGLE_CONSOLE_SETUP.md)）：
```bash
uv run email-assistant-config add-gmail personal-gmail
```
这将启动 Google 的 OAuth 同意屏幕，捕获刷新令牌并将其存储在 `~/.email_assistant_mcp/configs.json` 中。
### 3. 启动服务器
**适用于桌面客户端（stdio 传输协议）：**
```bash
uv run email-assistant-mcp --transport stdio
```
**适用于 Web 客户端（SSE 传输协议）：**
```bash
uv run email-assistant-mcp --transport sse --host 127.0.0.1 --port 8000 --sse-path /sse
```
**与 Claude Desktop 结合使用：** 参见 [Claude Desktop 设置指南](Documentation/CLAUDE_DESKTOP_SETUP.md)，以获取在 Claude Desktop 中配置 MCP 服务器的详细说明。
## 可用工具
MCP 服务器提供以下工具组：
### 初始化工具
- `health_check` - 验证服务器是否运行
- `list_email_accounts` - 显示已配置的账户
- `activate_email_account` - 切换活动账户
- `setup_gmail_account` - 通过 OAuth 配置新的 Gmail 账户
### 邮件操作
- `batch_move_emails` - 高效移动多封邮件（支持每封邮件不同的目标）
### 消息工具
- `search_mailbox` - 查找符合条件的邮件
### 规则工具
- `create_rule` - 定义邮件分类自动化规则
- `list_rules` - 显示所有已配置的规则
- `update_rule` - 修改现有规则
- `delete_rule` - 删除规则
### 管理工具
- `manage` - 集成工作流，获取消息、活动规则和文件夹
### 文件夹工具
- `list_folders` - 检索可用的邮件文件夹/标签
## MCP 资源
某些工具使用 `resource://` URI 进行大数据载体，需要 MCP 客户端调用 `resources/read` 并携带 URI 以获取实际内容：
- `list_email_folders` - 文件夹列表作为资源暴露
- `fetch_email_full` - 完整的消息内容，包含所有头部和附件
- `draft_email` - 草稿预览数据
**直接返回内联数据的工具（无需资源 URI）：**
- `get_emails` - 直接在响应中返回消息
- `manage` - 在响应中直接返回消息、规则和文件夹，以方便集成工作流
## 配置
### 邮件账户
邮件账户凭证存储在 `~/.email_assistant_mcp/configs.json` 中。每个账户都有一个 `config_id`，并包含：
```json
{
"provider": "gmail",
"email_address": "me@example.com",
"display_name": "My Name",
"refresh_token": "<oauth-refresh-token>",
"client_id": "<google-oauth-client-id>",
"client_secret": "<google-oauth-client-secret>"
}
```
**重要：** 参见 [GOOGLE_CONSOLE_SETUP.md](Documentation/GOOGLE_CONSOLE_SETUP.md)，以获取有关防止 OAuth 令牌在 7 天后过期的说明。
### 日志记录
通过环境变量配置日志记录：
- `EMAIL_ASSISTANT_LOG_FILE` - 日志文件路径（默认：`~/.email_assistant_mcp/logs/server.log`）
- `EMAIL_ASSISTANT_LOG_LEVEL` - 日志级别（默认：`INFO`）
- `EMAIL_ASSISTANT_LOG_FORMAT` - 输出格式：`text` 或 `json`（默认：`text`）
日志自动隐藏敏感数据（电子邮件地址、令牌、密码）。
## 开发
### 项目结构
```
email_assistant_mcp/
├── email_assistant_mcp/ # 主包
│ ├── server.py # FastMCP 服务器启动
│ ├── config.py # 配置模式
│ ├── credential_store.py # 凭证管理
│ ├── email_clients/ # 电子邮件提供商实现
│ └── tools/ # MCP 工具定义
├── tests/ # 单元测试
├── data/
│ └── rules/ # JSON 规则定义
└── Playground/ # 临时笔记本和原型
```
### 运行测试
```bash
pytest
```
或使用覆盖率：
```bash
pytest --cov=email_assistant_mcp
```
### 添加功能
1. 新的邮件操作放在 `email_assistant_mcp/email_clients/` 中
2. 新的 MCP 工具放在 `email_assistant_mcp/tools/` 中
3. 在 `email_assistant_mcp/tools/__init__.py` 中注册新工具
4. 在 `tests/` 下添加测试
## 文档
详尽的指南位于 [Documentation](Documentation/) 文件夹中：
- **[Claude Desktop 设置指南](Documentation/CLAUDE_DESKTOP_SETUP.md)** - 配置 Claude Desktop 以使用此 MCP 服务器
- **[Google 控制台设置指南](Documentation/GOOGLE_CONSOLE_SETUP.md)** - 设置 OAuth 凭证并防止令牌过期
- **[贡献指南](Documentation/CONTRIBUTING.md)** - 开发指南、代码标准和拉取请求流程
- **[项目指南（CLAUDE.md）](Documentation/CLAUDE.md)** - 内部架构和实现模式
## 许可证
该项目根据 MIT 许可证授权 - 详见 [LICENSE](LICENSE) 文件了解详情。
## 贡献
欢迎贡献！请阅读 [CONTRIBUTING.md](Documentation/CONTRIBUTING.md) 以获取有关以下内容的详细信息：
- 设置开发环境
- 代码标准和样式指南
- 测试要求
- 拉取请求流程
- 报告错误和请求功能
如有疑问或需要支持，请在 GitHub 上提出问题。
