Gmail MCP 服务器

本项目实现了一个模型上下文协议（MCP）服务器，允许通过 IMAP 和 SMTP 与 Gmail 账户进行交互。它提供了搜索电子邮件、检索内容、管理标签（创建、删除、重命名、应用、移除）以及发送/转发电子邮件的工具。

功能特性

• 电子邮件搜索： 按日期范围、关键词或原始 Gmail 查询字符串搜索电子邮件。支持搜索特定文件夹（收件箱、已发送）并限制结果数量。利用 Gmail 的 X-GM-RAW 扩展实现高效的收件箱搜索（例如，按 category:primary 过滤）。

• 电子邮件内容检索： 使用序列 ID 获取特定电子邮件的完整内容（标头、正文、附件）。

• 标签管理（增删改查）：

  • 列出所有可用的 Gmail 标签（文件夹）。

  • 创建新的自定义标签。

  • 重命名现有的自定义标签。

  • 删除现有的自定义标签（无法删除系统标签）。

  • 将标签应用于单个电子邮件。

  • 从单个电子邮件中移除标签。

• 批量操作：

  • 使用序列 ID 同时将标签应用于多封电子邮件。

  • 同时从多封电子邮件中移除标签。

  • 将多封电子邮件移动到特定标签/文件夹。

• 发送电子邮件： 发送新电子邮件（需要 SMTP 配置）。

• 转发电子邮件： 转发现有电子邮件，包括附件（需要 SMTP 配置）。

• 每日邮件计数： 统计指定日期范围内每天收到的电子邮件数量。

Related MCP server: Gmail MCP Server

项目结构

.
├── .gitignore         # Specifies intentionally untracked files that Git should ignore
├── .python-version    # Specifies Python version (used by pyenv)
├── LICENSE            # Project license file
├── pyproject.toml     # Python project configuration (dependencies, build system)
├── README.md          # This file
├── task_list.md       # Tracks development progress
├── uv.lock            # Lock file for uv package manager
├── src/
│   └── email_client/
│       ├── __init__.py
│       ├── config.py        # Handles loading configuration from environment variables (.env)
│       ├── handlers.py      # Implements the logic for handling MCP tool calls
│       ├── imap_client.py   # Contains functions for interacting with IMAP server
│       ├── server.py        # Main MCP server script using @modelcontextprotocol/sdk
│       ├── smtp_client.py   # Contains functions for interacting with SMTP server
│       ├── tool_definitions.py # Defines the available MCP tools and their schemas
│       └── utils.py         # Utility functions (e.g., email parsing, date formatting)
└── ... (other potential files like test scripts, helper scripts)

设置

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

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

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

   # Ensure uv is installed (e.g., pip install uv)
   uv venv  # Create virtual environment (.venv)
   uv sync  # Install dependencies from pyproject.toml and uv.lock
   source .venv/bin/activate # Activate the virtual environment

   （或者，如果不使用 uv，可以创建虚拟环境并在生成 requirements.txt 后使用 pip install -r requirements.txt 进行安装。）

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

   # .env file
   GMAIL_EMAIL=your_email@gmail.com
   GMAIL_PASSWORD=your_app_password # Use an App Password if 2FA is enabled
   GMAIL_IMAP_SERVER=imap.gmail.com
   GMAIL_SMTP_SERVER=smtp.gmail.com
   GMAIL_SMTP_PORT=587 # Or 465 for SSL

   • 重要提示： 对于 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": {}, // Environment variables are loaded from .env by the script
      "enabled": true, // Set to true to enable
      "autoApprove": [] // Configure auto-approval if desired
    }
    // ... other servers
  }
}

• 将 /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。