MCP Gmail Server

MCP Gmail Server

一个为大模型提供 Gmail 访问能力的 Model Context Protocol（MCP）服务，由 MCP Python SDK 提供支持。

功能

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

先决条件

• Python 3.10+
• 拥有 API 访问权限的 Gmail 账号
• 用于 Python 包管理的 uv（推荐）

设置

1. 安装依赖项

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

uv sync

2. 配置 Gmail OAuth 凭据

遗憾的是，使用 Gmail API 需要完成许多步骤。我已尽力整理截至 2025 年 3 月 28 日所需的所有步骤，但具体流程可能会发生变化。

Google Cloud 设置

1. 创建 Google Cloud 项目

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

2. 启用 Gmail API

   • 在 Google Cloud 项目中，前往导航菜单（≡）
   • 选择“API 和服务” > “库”
   • 搜索“Gmail API”
   • 点击 Gmail API 卡片
   • 点击“启用”

3. 配置 OAuth 同意屏幕

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

4. 创建 OAuth 凭据

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

5. 添加范围

   • 前往“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

说明

如果启动 Claude Desktop 并初始化 MCP 服务时遇到类似 Error: spawn uv ENOENT 的错误，你可能需要更新 claude_desktop_config.json，以提供 uv 的绝对路径。前往 Claude Desktop -> Settings -> Developer -> Edit Config。

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

开发

代码检查和测试

运行代码检查和格式化：

# Format code
uv run ruff format .

# Lint code with auto-fixes where possible
uv run ruff check --fix .

# Run tests
uv run pytest tests/

Pre-commit 钩子

本项目使用 pre-commit 钩子来确保代码质量。每次提交前都会自动运行这些钩子，以检查代码格式和代码检查标准。

安装 pre-commit 钩子：

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