AI导哈

Gmail智能集成服务

一个为Gmail和Google Calendar提供智能、上下文感知交互的模型上下文协议（MCP）服务器，集成于Claude Desktop中。

  • by bastienchabal
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 bastienchabal/gmail-mcp

使用说明

Gmail MCP服务器

用于Gmail和Google日历与Claude Desktop集成的模型上下文协议（MCP）服务器，可与您的电子邮件进行智能、上下文感知的交互。

🌟 特性

  • 深度电子邮件分析：提供整个对话线程的全面上下文
  • 上下文感知响应：根据完整的通信历史生成响应
  • 智能行动建议：分析日历事件、任务和跟进的电子邮件内容
  • 日历集成：检测电子邮件中的事件，并使用自然语言支持创建日历条目
  • 高级搜索：通过语义理解在整个电子邮件历史记录中搜索
  • 个性化：适应您与特定联系人的沟通风格

🚀 入门指南

先决条件

  • Python 3.10+
  • 启用Gmail API和Google日历API（可选）的Google云平台帐户
  • Gmail API和Google Calendar API的OAuth 2.0凭据（可选）
  • 支持MCP的Claude Desktop（目前只有LLM接口支持MCP）

安装

通过Smithery安装

通过以下方式自动安装适用于Claude Desktop的Gmail集成服务器 史密瑟里:

npx -y @smithery/cli install @bastienchabal/gmail-mcp --client claude

手动安装

  1. 克隆此存储库：

    git clone https://github.com/bastienchabal/gmail-mcp.git
cd gmail-mcp

  2. 使用uv设置虚拟环境：

    pip install uv
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

  3. 安装依赖项：

    uv pip install -e .

⚙️ 配置

第一步：通过谷歌进行身份验证

  1. 转到 谷歌云控制台
  2. 创建新项目或选择现有项目
  3. 启用Google API：
  4. 配置 OAuth同意屏幕:
    • 选择“外部”用户类型
    • 将您的电子邮件添加为测试用户
    • 添加所有 范围 Gmail和日历
  5. 创建 OAuth 2.0凭据:
    • 选择“桌面应用程序”作为应用程序类型
    • 下载JSON凭据文件并复制客户端ID和客户端密码

步骤2：配置Claude桌面

  1. 创建或编辑 claude_desktop_config.json 文件在 /Users/<username>/Library/Application Support/Claude
  2. 添加以下配置，用实际值替换占位符：
{
  "mcpServers": {
    "gmail-mcp": {
      "command": "/<absolute-path>/gmail-mcp/.venv/bin/mcp",
      "args": [
        "run",
        "/<absolute-path>/gmail-mcp/gmail_mcp/main.py:mcp"
      ],
      "cwd": "/<absolute-path>/gmail-mcp",
      "env": {
        "PYTHONPATH": "/<absolute-path>/gmail-mcp",
        "CONFIG_FILE_PATH": "/<absolute-path>/gmail-mcp/config.yaml",
        "GOOGLE_CLIENT_ID": "<your-client-id>",
        "GOOGLE_CLIENT_SECRET": "<your-client-secret>",
        "TOKEN_ENCRYPTION_KEY": "<generate-a-random-key>"
      }
    }
  }
}

笔记：

  • 替换 <absolute-path> 带有gmailmcp目录的实际路径
  • 替换 <your-client-id> 和 <your-client-secret> 使用您的Google OAuth凭据（之前在json文件中生成）
  • 可选：使用以下内容生成随机加密密钥： python -c "import os; from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

该配置旨在将敏感数据（客户端ID、客户端机密和加密密钥）保存在Claude Desktop配置文件中，而非敏感设置存储在存储库中包含的config.yaml文件中。

步骤3：使用克劳德桌面

  1. 打开克劳德桌面
  2. 键入类似“请检索我的最后一封电子邮件”的提示
  3. Claude应该自动连接到MCP服务器，并要求您对您的Gmail帐户进行身份验证（创建文件token.json）

❓ 故障排除

关于MCP的重要说明

如果Claude Desktop没有自动连接（即您在提示输入下方看不到工具图标），您可以尝试：

  • 重新启动克劳德桌面
  • 要求克劳德“使用Gmail MCP服务器”
  • 使用以下方法之一手动登录Gmail：

关于身份验证的重要说明

  1. 身份验证问题:

    • 跑 python debug/auth_test.py 使用详细的反馈测试身份验证过程
    • 检查令牌文件是否存在于项目根目录下
    • 验证您的Google Cloud Console项目是否配置了正确的重定向URI
    • 确保所有必需的范围都已添加到OAuth同意屏幕中
    • 如果您看到“范围已更改”错误，请确保 openid 范围包含在OAuth同意屏幕中
    • 如果您看到“redirect_uri_mismatch”错误，请将错误消息中显示的确切uri添加到Google Cloud Console中的授权重定向uri中
    • 如果回调页面没有正确加载或处理，请检查端口8000是否已被其他应用程序使用

  2. 日历API问题:

    • 确保您已在Google云控制台中启用日历API
    • 检查您是否在身份验证期间授予了所有必要的作用域
    • 跑 python debug/reauth_calendar.py 使用日历API作用域重新进行身份验证
    • 核实一下 CALENDAR_API_ENABLED 设置为 true 在环境变量中

关于日历集成的重要提示

可以在配置文件中关闭日历集成。如果您以前使用Gmail MCP服务器进行过身份验证，现在正在启用日历集成，则需要重新进行身份验证才能授予额外的日历API作用域。您可以通过以下方式做到这一点：

  1. 删除现有的tokens.json文件（如果存在，可以在projet根目录或~/Users中删除/<username/>gmail_mcp_tokens/tokens.json）
  2. 重新启动MCP服务器
  3. 再次执行身份验证过程

👤 用法

Gmail MCP提供了强大的上下文感知工具来管理您的电子邮件和日历：

电子邮件管理

  • 电子邮件概述：通过计数和最近的电子邮件全面查看收件箱
  • 高级搜索：使用Gmail强大的搜索语法查找特定电子邮件
  • 详细的电子邮件分析：查看具有完整上下文的电子邮件，包括线程历史记录和发件人信息

上下文感知电子邮件回复

  • 智能回复准备：在回复之前分析电子邮件线程的完整上下文
  • 沟通模式分析：了解您与发件人的通信历史
  • 个性化绘图：创建与特定联系人的沟通风格相匹配的回复草稿
  • 实体识别：识别电子邮件中的重要日期、时间、行动项和其他实体
  • 相关电子邮件上下文：在制作回复时考虑其他相关电子邮件

日历集成

  • 事件创建：使用自然语言时间描述创建日历事件
  • 事件检测：自动检测电子邮件中提到的潜在事件
  • 日历管理：查看、搜索和管理您即将到来的日历事件
  • 智能调度：根据电子邮件对话中的适当背景安排会议

请求示例

你可以让Claude在自然语言请求中使用这些功能，比如：

  • “显示收件箱概览”
  • “查找我老板关于季度报告的所有未读电子邮件”
  • “帮我回复Sarah关于项目截止日期的最后一封电子邮件”
  • “为John电子邮件中提到的团队会议创建日历事件”
  • “我下周安排了哪些会议？”
  • “在我回复之前，分析这封电子邮件的主题并帮助我理解要点”
  • “考虑到我之前与此人的沟通，起草对此电子邮件的回复”

可用资源

MCP提供了丰富的上下文资源，Claude可以访问：

  • 电子邮件上下文：特定电子邮件的详细信息
  • 线程上下文：电子邮件线程的完整对话历史记录
  • 发件人上下文：有关您与发件人的关系和沟通历史的信息
  • 身份验证状态：当前与Google的身份验证状态
  • Gmail状态：您的Gmail帐户概述
  • 服务器信息：有关MCP服务器配置的详细信息

可用指南

MCP包括几个指南，以帮助您充分利用其功能：

  • 快速入门指南：入门的基本说明
  • 身份验证指南：帮助进行身份验证过程
  • 搜索指南：高级Gmail搜索语法参考
  • 回复指南：上下文感知电子邮件回复的最佳实践
  • 调试指南：常见问题的故障排除

☑️ 此MCP已配置，因此克劳德在执行任何重要操作（如发送电子邮件或创建会议）之前，始终会要求您进行确认。

⚠ Beta通知

此MCP是WIP，目前处于测试阶段。

📝 许可证

该项目根据MIT许可证获得许可。

💡 致谢

  • 本项目使用Anthropic开发的模型上下文协议（MCP）
  • Gmail API访问由谷歌的API服务提供

相关 MCP