AI导哈

Gmail访问服务

一个基于MCP协议的Gmail访问服务器，为大型语言模型提供电子邮件管理功能。

  • by jeremyjordan
  • Python
  • 本地部署
  • 10 星标
  • 更新于
在 GitHub 查看 jeremyjordan/mcp-gmail

使用说明

MCP Gmail服务器

一种模型上下文协议（MCP）服务器，为LLM提供Gmail访问，由 MCP Python SDK.

特性

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

先决条件

  • Python 3.10+
  • 可访问API的Gmail帐户
  • 紫外线 用于Python包管理（推荐）

设置

1.安装依赖项

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

uv sync

2.配置Gmail OAuth凭据

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

谷歌云设置

  1. 创建谷歌云项目

    • 首选 谷歌云控制台
    • 点击页面顶部的项目下拉列表
    • 点击“新建项目”
    • 输入项目名称（例如“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. 添加作用域

    • 转到“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检查器应用程序，您可以使用它与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

[！注意] 如果你遇到这样的错误 Error: spawn uv ENOENT 启动Claude Desktop并初始化MCP服务器时，您可能需要更新 claude_desktop_config.json 提供 绝对的 通往 uv.转到克劳德桌面->设置->开发人员->编辑配置。

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

发展

剥皮和测试

运行linting和格式化：

# Format code
uv run ruff format .

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

# Run tests
uv run pytest tests/

预提交钩子

这个项目使用预提交挂钩来确保代码质量。钩子在每次提交之前自动运行，以验证代码格式和linting标准。

安装预提交挂钩：

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

许可证

麻省理工学院

相关 MCP