MCP 服务器

Gmail MCP Server

用于通过 IMAP 和 SMTP 与 Gmail 交互的 MCP 服务器 (Or, more literally: 用于通过 IMAP 和 SMTP 与 Gmail 交互的 MCP 服务器) **Explanation of Choices:** * **MCP Server:** I kept "MCP Server" as is, assuming it's a specific term or acronym that's best left untranslated. If you have more context about what "MCP" stands for, I can provide a more accurate translation. * **用于 (yòng yú):** Means "used for" or "for the purpose of." * **通过 (tōng guò):** Means "through" or "via." * **IMAP 和 SMTP (IMAP hé SMTP):** These are standard internet protocols and are commonly used in their English abbreviations in Chinese technical contexts. * **与 (yǔ):** Means "with" or "and." * **Gmail 交互 (Gmail jiāo hù):** Means "Gmail interaction" or "interacting with Gmail." The second, more literal translation is included because sometimes in technical contexts, a more direct translation is preferred. However, the first option is generally more natural-sounding in Chinese.

david-strejc

开发者工具

访问服务器

README

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 # 定义可用的 MCP 工具及其模式
│       └── utils.py         # 实用函数（例如，电子邮件解析、日期格式化）
└── ... (其他潜在文件，如测试脚本、辅助脚本)

设置

克隆存储库（如果适用）：

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

安装依赖项： 本项目使用 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 文件。)

配置环境变量： 在项目根目录中创建一个 .env 文件，并添加您的 Gmail 凭据和服务器设置：
```
# .env 文件
GMAIL_EMAIL=your_email@gmail.com
GMAIL_PASSWORD=your_app_password # 如果启用了 2FA，请使用应用密码
GMAIL_IMAP_SERVER=imap.gmail.com
GMAIL_SMTP_SERVER=smtp.gmail.com
GMAIL_SMTP_PORT=587 # 或者 465 用于 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": {}, // 环境变量由脚本从 .env 加载
      "enabled": true, // 设置为 true 以启用
      "autoApprove": [] // 如果需要，配置自动批准
    }
    // ... 其他服务器
  }
}