MCP Gmail Server

这是一个提供LLMs访问Gmail功能的Model Context Protocol（MCP）服务器，由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控制台
   • 点击页面顶部的项目下拉菜单
   • 点击“新建项目”
   • 输入项目名称（例如，“MCP Gmail集成”）
   • 点击“创建”
   • 等待项目创建完成，并从下拉菜单中选择它

2. 启用Gmail API

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

3. 配置OAuth同意屏幕

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

4. 创建OAuth凭证

   • 转到“API和服务” > “凭证”
   • 点击“创建凭证” > “OAuth客户端ID”
   • 选择“桌面应用”作为应用程序类型
   • 输入一个名称（例如，“MCP Gmail桌面客户端”）
   • 点击“创建”
   • 点击下载您刚刚创建的凭证的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

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

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

开发

代码检查和测试

运行代码检查和格式化：

# 格式化代码
uv run ruff format .

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

# 运行测试
uv run pytest tests/

提交前钩子

此项目使用提交前钩子来确保代码质量。这些钩子会在每次提交前自动运行，以验证代码格式和代码检查标准。

安装提交前钩子：

pre-commit install

手动在所有文件上运行提交前钩子：

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：搜索查询的默认最大结果数（默认：110）

许可证

MIT