MCP Gmail 服务器

一个模型上下文协议 (MCP) 服务器，为 LLM 提供 Gmail 访问，由 MCP Python SDK 驱动。

特性

• 将 Gmail 消息公开为 MCP 资源
• 提供用于撰写、发送和管理电子邮件的工具
• 使用 Google 的 Gmail API 进行 OAuth 2.0 身份验证

前提条件

• Python 3.10+
• 具有 API 访问权限的 Gmail 帐户
• uv 用于 Python 包管理（推荐）

设置

1. 安装依赖项

安装项目依赖项（uv 自动创建和管理虚拟环境）

uv sync

2. 配置 Gmail OAuth 凭据

不幸的是，使用 Gmail API 需要很多步骤。 我试图捕获所有必需的步骤（截至 2025 年 3 月 28 日），但情况可能会发生变化。

Google Cloud 设置

1. 创建一个 Google Cloud 项目

   • 转到 Google Cloud Console
   • 点击页面顶部的项目下拉菜单
   • 点击“新建项目”
   • 输入项目名称（例如，“MCP Gmail 集成”）
   • 点击“创建”
   • 等待项目创建完成，然后从下拉菜单中选择它

2. 启用 Gmail API

   • 在您的 Google Cloud 项目中，转到导航菜单 (≡)
   • 选择“API 和服务”>“库”
   • 搜索“Gmail API”
   • 点击 Gmail API 卡片
   • 点击“启用”

3. 配置 OAuth 同意屏幕

   • 转到“API 和服务”>“OAuth 同意屏幕”
   • 您可能会看到类似“Google Auth Platform 尚未配置”的内容
     • 点击“开始使用”
   • 填写所需的应用程序信息：
     • 应用名称：“MCP Gmail 集成”
     • 用户支持电子邮件：您的电子邮件地址
   • 填写所需的用户信息：
     • 选择“外部”用户类型（除非您拥有 Google Workspace 组织）
   • 填写所需的联系信息：
     • 您的电子邮件地址
   • 点击“保存并继续”
   • 点击“创建”

4. 创建 OAuth 凭据

   • 转到“API 和服务”>“凭据”
   • 点击“创建凭据”>“OAuth 客户端 ID”
   • 选择“桌面应用”作为应用程序类型
   • 输入名称（例如，“MCP Gmail 桌面客户端”）
   • 点击“创建”
   • 点击“下载 JSON”以下载您刚刚创建的凭据
   • 将文件另存为项目根目录中的 credentials.json

5. 添加 scopes

   • 转到“API 和服务”>“OAuth 同意屏幕”
   • 转到“数据访问”选项卡
   • 点击“添加或删除范围”
   • 搜索 Gmail API
   • 选择 .../auth/gmail.modify 的范围，该范围授予“从您的 Gmail 帐户读取、撰写和发送电子邮件”的权限
   • 点击更新
   • 点击保存

通过运行一个简单的测试脚本来验证您是否已正确设置 OAuth 配置。

uv run python scripts/test_gmail_setup.py

您应该能够在 https://console.cloud.google.com/apis/api/gmail.googleapis.com/metrics 上看到使用情况指标

3. 运行服务器

开发模式：

uv run mcp dev mcp_gmail/server.py

这将启动一个 MCP Inspector 应用程序，您可以使用它与 MCP 服务器进行交互。

或者安装以与 Claude Desktop 一起使用：

uv run mcp install \
    --with-editable .
    --name gmail \
    --env-var MCP_GMAIL_CREDENTIALS_PATH=$(pwd)/credentials.json \
    --env-var MCP_GMAIL_TOKEN_PATH=$(pwd)/token.json \
    mcp_gmail/server.py

[!NOTE] 如果您在启动 Claude Desktop 并初始化 MCP 服务器时遇到类似 Error: spawn uv ENOENT 的错误，您可能需要更新您的 claude_desktop_config.json 以提供 uv 的绝对路径。 转到 Claude Desktop -> 设置 -> 开发者 -> 编辑配置。

{
  "mcpServers": {
    "gmail": {
      "command": "~/.local/bin/uv",
    }
  }
}

开发

Linting 和测试

运行 linting 和格式化：

# 格式化代码
uv run ruff format .

# 使用自动修复功能检查代码
uv run ruff check --fix .

# 运行测试
uv run pytest tests/

Pre-commit Hooks

该项目使用 pre-commit hooks 来确保代码质量。 这些 hooks 在每次提交之前自动运行，以验证代码格式和 linting 标准。

安装 pre-commit hooks：

pre-commit install

手动对所有文件运行 pre-commit：

pre-commit run --all-files

用法

运行后，您可以使用任何 MCP 客户端或通过 Claude Desktop 连接到 MCP 服务器。

可用资源

• gmail://messages/{message_id} - 访问电子邮件消息
• gmail://threads/{thread_id} - 访问电子邮件线程

可用工具

• compose_email - 创建新的电子邮件草稿
• send_email - 发送电子邮件
• search_emails - 使用特定过滤器（发件人、收件人、主题、日期等）搜索电子邮件
• query_emails - 使用原始 Gmail 查询语法搜索电子邮件
• get_emails - 按 ID 检索多个电子邮件消息
• list_available_labels - 获取所有可用的 Gmail 标签
• mark_message_read - 将消息标记为已读
• add_label_to_message - 向消息添加标签
• remove_label_from_message - 从消息中删除标签

环境变量

您可以使用环境变量配置服务器：

• MCP_GMAIL_CREDENTIALS_PATH: OAuth 凭据 JSON 文件的路径（默认值：“credentials.json”）
• MCP_GMAIL_TOKEN_PATH: 存储 OAuth 令牌的路径（默认值：“token.json”）
• MCP_GMAIL_MAX_RESULTS: 搜索查询的默认最大结果数（默认值：10）

许可证

MIT