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        # 主MCP服务器脚本，使用@modelcontextprotocol/sdk
│       ├── smtp_client.py   # 包含与SMTP服务器交互的函数
│       ├── tool_definitions.py # 定义可用的MCP工具及其模式
│       └── utils.py         # 工具函数（如邮件解析、日期格式化）
└── ... (其他可能的文件，如测试脚本、辅助脚本)

设置

1. 克隆仓库（如果适用）：

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

2. 安装依赖项： 该项目使用uv进行包管理。

   # 确保已安装uv（例如，pip install uv）
   uv venv  # 创建虚拟环境(.venv)
   uv sync  # 根据pyproject.toml和uv.lock安装依赖项
   source .venv/bin/activate # 激活虚拟环境
   

   (如果不使用uv，可以创建一个虚拟环境，并使用pip install -r requirements.txt安装，如果生成了requirements.txt文件的话）。

3. 配置环境变量： 在项目根目录下创建一个.env文件，并添加您的Gmail凭据和服务器设置：

   # .env 文件
   GMAIL_EMAIL=your_email@gmail.com
   GMAIL_PASSWORD=your_app_password # 如果启用了两步验证，请使用应用密码
   GMAIL_IMAP_SERVER=imap.gmail.com
   GMAIL_SMTP_SERVER=smtp.gmail.com
   GMAIL_SMTP_PORT=587 # 或者使用SSL的465
   

   • 重要： 对于Gmail，如果您启用了两步验证，您必须生成并使用“应用密码”。标准密码将不起作用。参见Google关于应用密码的文档。
   • 如果您不使用两步验证，请确保启用了“不太安全的应用访问”（这通常不被推荐）。

运行MCP服务器

激活虚拟环境并运行服务器脚本：

source .venv/bin/activate
python src/email_client/server.py

服务器将启动并监听标准输入/输出的MCP请求。

集成到MCP客户端（例如Cline）

在您的MCP客户端设置文件（例如cline_mcp_settings.json或claude_desktop_config.json）中添加服务器配置。

示例cline_mcp_settings.json条目：

{
  "mcpServers": {
    "gmail": {
      "command": "/path/to/your/project/gmail-mcp-server/.venv/bin/python",
      "args": ["/path/to/your/project/gmail-mcp-server/src/email_client/server.py"],
      "env": {}, // 环境变量由脚本从.env加载
      "enabled": true, // 设置为true以启用
      "autoApprove": [] // 如有需要，配置自动批准
    }
    // ... 其他服务器
  }
}

• 将/path/to/your/project/gmail-mcp-server替换为此项目的实际绝对路径。
• 确保command指向项目虚拟环境中的Python可执行文件（.venv/bin/python）。

配置并启用后，客户端应连接到服务器，定义的工具将变得可用。

可用工具（概述）

• 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了解每个工具的详细输入模式。