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 # 定义所有可用工具及其详细输入模式

快速开始

1. 克隆仓库:

   git clone https://github.com/yourusername/gmail-mcp-server.git
   cd gmail-mcp-server
   

2. 创建虚拟环境并安装依赖项:

   python -m venv .venv
   source .venv/bin/activate  # 在 Windows 上使用 .venv\Scripts\activate
   pip install -r requirements.txt
   

3. 配置环境变量: 创建一个 .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
   

4. 运行服务器:

   source .venv/bin/activate  # 在 Windows 上使用 .venv\Scripts\activate
   python src/email_client/server.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。