Gmail MCP Server

Gmail MCP 服务

此项目实现了一个模型上下文协议（MCP）服务，可通过 IMAP 和 SMTP 与 Gmail 帐户交互。它提供了用于搜索邮件、获取内容、管理标签（创建、删除、重命名、应用和移除）以及发送或转发邮件的工具。

功能

• 邮件搜索： 按日期范围、关键词或原始 Gmail 查询字符串搜索邮件。支持搜索特定文件夹（收件箱、已发送）并限制结果数量。使用 Gmail 的 X-GM-RAW 扩展高效搜索收件箱（例如，按 category:primary 筛选）。
• 邮件内容获取： 使用邮件序列 ID 获取特定邮件的完整内容（邮件头、正文、附件）。
• 标签管理（CRUD）：
  • 列出所有可用的 Gmail 标签（文件夹）。
  • 创建自定义标签。
  • 重命名现有自定义标签。
  • 删除现有自定义标签（无法删除系统标签）。
  • 为单封邮件应用标签。
  • 移除单封邮件的标签。
• 批量操作：
  • 使用序列 ID 同时为多封邮件应用标签。
  • 同时移除多封邮件的标签。
  • 将多封邮件移至指定标签/文件夹。
• 邮件发送： 发送新邮件（需要配置 SMTP）。
• 邮件转发： 转发现有邮件，包括附件（需要配置 SMTP）。
• 每日邮件数量： 统计指定日期范围内每天收到的邮件数量。

项目结构

.
├── .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
   [email protected]
   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 指向项目虚拟环境（.venv/bin/python）中的 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。