AI导哈

Gmail邮件管理服务器

一个基于MCP协议的Gmail邮件管理服务器，提供邮件搜索、内容检索、标签管理及邮件发送/转发功能。

  • by david-strejc
  • Python
  • 本地部署
  • 11 星标
  • 更新于
在 GitHub 查看 david-strejc/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，创建虚拟环境并使用进行安装 pip install -r requirements.txt 如果a 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，如果您启用了双因素身份验证，您 必须 生成并使用“应用程序密码”。标准密码不起作用。请参阅 谷歌关于应用密码的文档.
    • 如果您处于以下状态，请确保启用“不太安全的应用程序访问” 不 使用2FA（这通常是不鼓励的）。

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

相关 MCP