🚀 Gmail MCP 服务器
该项目实现了一个模型上下文协议 (MCP) 服务器，可借助 IMAP 和 SMTP 与 Gmail 账户进行交互。它提供了一系列实用工具，能用于搜索邮件、检索邮件内容、管理标签（创建、删除、重命名、应用、移除）以及发送/转发邮件。
✨ 主要特性
- 邮件搜索：可依据日期范围、关键字或原始 Gmail 查询字符串来搜索邮件。支持在特定文件夹（如收件箱、已发送）中搜索，并能限制搜索结果数量。借助 Gmail 的
X - GM - RAW扩展，能实现高效的收件箱搜索（例如按category:primary过滤）。 - 邮件内容检索：通过序列 ID 可获取特定邮件的完整内容，包括头信息、正文和附件。
- 标签管理 (CRUD)：
- 列出所有可用的 Gmail 标签（文件夹）。
- 创建新的自定义标签。
- 重命名现有的标签。
- 删除现有的自定义标签（系统标签无法删除）。
- 将标签应用到单个邮件上。
- 移除单个邮件上的标签。
- 批处理操作：
- 利用序列 ID 批量为多个邮件应用标签。
- 从多个邮件上批量移除标签。
- 将多个邮件移动到特定标签/文件夹中。
- 发送邮件：可发送新邮件（需要进行 SMTP 配置）。
- 转发邮件：能转发现有邮件，包括附件（需要进行 SMTP 配置）。
- 每日邮件计数：可统计指定日期范围内每天收到的邮件数量。
📚 详细文档
项目结构
.
├── .gitignore # 指定 Git 应忽略的文件
├── .python-version # 指定 Python 版本（用于 pyenv）
├── LICENSE # 项目许可证文件
├── pyproject.toml # Python 项目配置（依赖项、构建系统）
├── README.md # 此文件
├── task_list.md # 跟踪开发进度
├── uv.lock # uv 包管理器的锁定文件
├── src/
│ └── email_client/
│ ├── __init__.py
│ ├── config.py # 处理从环境变量（.env）加载配置
│ ├── handlers.py # 实现处理 MCP 工具调用逻辑
│ ├── imap_client.py # 包含与 IMAP 服务器交互的函数
│ ├── server.py # 使用 @modelcontextprotocol/sdk 的主 MCP 服务器脚本
│ ├── smtp_client.py # 包含与 SMTP 服务器交互的函数
│ └── tool_definitions.py # 定义所有可用工具及其详细输入模式
可用工具（摘要）
search - emails：搜索邮件。get - email - content：获取完整的邮件详情。count - daily - emails：统计每天收到的邮件数量。list - labels：列出所有标签/文件夹。create - label：创建新的标签。rename - label：重命名现有标签。delete - label：删除标签。apply - label：将标签应用到单个邮件上。remove - label：移除单个邮件上的标签。apply - label - batch：批量为多个邮件应用标签。remove - label - batch：从多个邮件上批量移除标签。move - email：将单个邮件移动到一个标签中。move - email - batch：将多个邮件移动到一个标签中。send - email：发送新邮件。forward - email：转发现有邮件。
有关每个工具的详细输入模式，请参阅 src/email_client/tool_definitions.py。
🚀 快速开始
- 克隆仓库：
git clone https://github.com/yourusername/gmail-mcp-server.git
cd gmail-mcp-server
- 创建虚拟环境并安装依赖项：
python -m venv .venv
source .venv/bin/activate # 在 Windows 上使用 .venv\Scripts\activate
pip install -r requirements.txt
- 配置环境变量：
创建一个
.env文件，添加以下内容：
Gmail_IMAP_HOST=imap.gmail.com
Gmail_SMTP_HOST=smtp.gmail.com
Gmail_PORT=143 # IMAP 端口
Gmail_SSL_PORT=465 # SMTP SSL 端口
Gmail_EMAIL=your_email@gmail.com
Gmail_PASSWORD=your_app_specific_password
- 运行服务器：
source .venv/bin/activate # 在 Windows 上使用 .venv\Scripts\activate
python src/email_client/server.py