mcp-gsuite-enhanced

mcp-gsuite-enhanced

功能全面的 Google Workspace MCP 服务，完整覆盖 Gmail API，并提供高级邮件管理功能

用于与 Google 产品交互的 MCP 服务，完整覆盖 Gmail API（共 27 个工具），提供高级邮件管理、标签操作、归档工作流，以及可正常使用的 Google Meet 集成功能。

目录

• 快速开始
• 增强功能
• 功能与能力
• 示例提示词
• 安装
• Google 身份验证设置
• 配置示例
• Google Meet 集成
• 开发
• 安全
• 致谢
• 许可证
• 贡献
• 支持

🚀 快速开始

只需 5 分钟，即可运行 Google Workspace MCP！

前提条件

• 已安装 Python 3.13+ 和 uv
• 拥有可访问 Gmail/Calendar 的 Google 账号
• Cursor IDE（推荐）或任意 MCP 客户端

步骤 1：克隆并安装

git clone https://github.com/ajramos/mcp-gsuite-enhanced.git
cd mcp-gsuite-enhanced
uv sync

步骤 2：设置 Google Cloud（一次性设置）

1. 前往 Google Cloud Console
2. 创建项目并启用 Gmail API 和 Google Calendar API
3. 创建 OAuth 2.0 Desktop 凭据
4. 下载凭据，并将其保存为项目目录中的 .gauth.json

步骤 3：配置账号

创建 .accounts.json：

{
  "accounts": [
    {
      "email": "[email protected]",
      "account_type": "personal", 
      "extra_info": "Main personal Gmail and Calendar"
    }
  ]
}

步骤 4：快速检查配置

python cursor_setup.py

这会显示身份验证状态并生成 Cursor 配置。

步骤 5：进行身份验证

python auth_setup.py [email protected]

浏览器将打开 OAuth 流程；授予权限后即可完成！

步骤 6：在 Cursor 中配置

1. 复制步骤 4 中的 JSON 配置
2. Cursor → Settings (Cmd+,) → 搜索 "MCP"
3. 粘贴配置并重启 Cursor

步骤 7：测试！🎉

在 Cursor 中试试以下命令：

• "列出我的日历"
• "显示未读邮件"
• "创建一个带 Google Meet 链接的测试会议"

就是这么简单！ 现在，你已拥有完整的 Google Workspace 集成，并可自动生成 Google Meet 链接！

---

🎯 增强功能 v2.0.0

🚀 完整覆盖 Gmail API（共 27 个工具）

• 22 个 Gmail 工具 — 完整管理邮件生命周期
• 5 个 Calendar 工具 — 完整集成日历和 Google Meet

✨ 高级邮件管理

• ✅ 发送邮件 — 直接通过 Gmail 发送
• ✅ 标签管理 — 创建、应用、移除和删除标签
• ✅ 归档工作流 — 归档、恢复并管理邮件生命周期
• ✅ 草稿管理 — 列出、创建和管理邮件草稿
• ✅ 批量操作 — 高效归档多封邮件
• ✅ 邮件状态 — 标记为已读/未读、移至垃圾箱

🎪 增强的日历功能

• ✅ 可正常使用的 Google Meet 集成 — 在日历活动中自动添加 Meet 链接
• ✅ 修复 update_calendar_event — 此功能之前无法使用，现在已完全正常
• ✅ 改进与会者处理 — 修复了电子邮件解析错误
• ✅ 设置工具 — 使用 auth_setup.py 和 cursor_setup.py 轻松完成配置

功能与能力

v2.0.0 提供全面的 Google Workspace 自动化功能，共包含 27 个工具：

1. 通用

• 支持多个 Google 账号
• 使用令牌刷新的 OAuth 2.0 身份验证
• 全面的错误处理和日志记录

2. Gmail（22 个工具）📧

电子邮件管理

• 通过 Gmail 直接发送电子邮件，支持抄送/密送
• 灵活搜索电子邮件（未读邮件、发件人、日期、附件）
• 按 ID 检索完整电子邮件内容，或一次检索多封电子邮件
• 将电子邮件标记为已读/未读
• 将电子邮件移至垃圾箱

草稿管理

• 创建新的电子邮件草稿，可设置收件人、主题、正文和抄送选项
• 列出所有草稿邮件及完整详情
• 删除草稿邮件
• 回复现有邮件（立即发送或保存为草稿）

标签管理 🏷️

• 列出所有 Gmail 标签（系统标签和自定义标签）
• 创建新的自定义标签
• 为电子邮件添加标签
• 移除电子邮件上的标签
• 永久删除自定义标签

归档工作流 📁

• 归档单封邮件（从收件箱中移除）
• 一次归档多封邮件（批量操作）
• 列出已归档邮件
• 将已归档邮件恢复至收件箱

附件管理

• 下载电子邮件附件并保存为本地文件
• 批量保存不同邮件中的多个附件

3. 日历（5 个工具）📅

• 列出账号中可用的日历
• 获取指定时间范围内的日历活动
• 创建包含参与者的日历活动，并自动生成 Google Meet 链接 🎪
• 更新现有日历活动（摘要、时间、参与者）⚡
• 删除日历活动
• 完整支持时区，方便安排国际日程

💡 可尝试的示例提示词

📧 Gmail 操作（22 个工具）

• 电子邮件搜索与检索

  • “检索我最新的未读邮件”
  • “搜索 Scrum Master 发给我的邮件”
  • “显示本周所有带附件的邮件”
  • “获取关于 ABC 的邮件并进行总结”

• 撰写与管理电子邮件

  • “给 [email protected] 发送一封关于项目进展的邮件”
  • “为 Alice 的上一封邮件写一封得体的回复，并保存为草稿”
  • “将 [email protected] 发来的所有邮件标记为已读”
  • “将那封垃圾邮件移至垃圾箱”

• 标签管理 🏷️

  • “创建一个名为‘Project Alpha’的标签，并应用到关于该项目的邮件”
  • “显示我的所有自定义标签”
  • “移除昨天那封邮件上的‘Urgent’标签”
  • “删除未使用的‘Old Project’标签”

• 归档工作流 📁

  • “归档上周的所有新闻简报邮件”
  • “显示我第三季度的已归档邮件”
  • “将那封重要邮件恢复至收件箱”
  • “一次归档这 5 封邮件：[email IDs]”

• 附件管理

  • “下载包含‘invoice’的邮件中的所有附件”
  • “保存本周 [email protected] 发来的所有邮件附件”

📅 日历管理

• 日程与安排

  • “我明天有什么安排？”
  • “查看我私人账号中下周的家庭日程”
  • “我需要下周和 Tim 安排一场 2 小时的活动。请推荐一些时间段”

• 创建含 Google Meet 的活动 🎪

  • “下周五与 John 创建会议，并附上 Google Meet 链接”
  • “安排周四下午 2 点的客户通话，并邀请 [email protected]”
  • “创建每周一上午 9 点举行的团队每日站会，并使用 Google Meet”
  • “创建明天下午 3 点的项目评审会议，附上 Google Meet 链接并邀请整个团队”

• 更新活动 ⚡ （增强功能）

  • “将 Sarah 添加为我下午 3 点会议的参与者”
  • “更新季度规划会议，将时间改为下午 4 点，并添加 [email protected]”
  • “将明天团队会议的地点改为 B 会议室”

• 高级日历查询

  • “列出我下周所有带 Google Meet 链接的日历活动”
  • “显示我本月所有的定期会议”
  • “查找下周安排的所有包含外部参与者的会议”

安装

选项 1：通过 Smithery 快速安装（推荐）📦

开始使用 MCP GSuite Enhanced 的最快方式：

npx -y @smithery/cli install mcp-gsuite-enhanced --client claude

这将自动：

• ✅ 下载并安装最新版本
• ✅ 为你配置 Claude Desktop
• ✅ 设置 MCP 服务条目

选项 2：手动安装 🔧

适用于高级用户或开发用途：

Cursor IDE 设置

Cursor IDE 用户可以使用设置辅助脚本：

python cursor_setup.py

此脚本将生成正确的 MCP 配置，并提供分步说明，指导你将其添加到 Cursor 设置中。

使用 uv 手动安装（推荐）

git clone https://github.com/ajramos/mcp-gsuite-enhanced
cd mcp-gsuite-enhanced
uv sync

使用 pip 手动安装

git clone https://github.com/ajramos/mcp-gsuite-enhanced
cd mcp-gsuite-enhanced
pip install -e .

设置 Google 身份验证

Google Cloud 配置

你需要创建一个 Google Cloud 项目并配置 OAuth2 凭据：

步骤 1：创建 Google Cloud 项目

1. 前往 Google Cloud Console
2. 创建新项目或选择现有项目
3. 启用所需的 API：
   • 前往“API 和服务” → “库”
   • 搜索 “Gmail API” 并启用
   • 搜索 “Google Calendar API” 并启用

步骤 2：设置 OAuth 2.0 凭据

1. 前往“API 和服务” → “凭据”
2. 点击“创建凭据” → “OAuth 客户端 ID”
3. 选择 “桌面应用” 作为应用类型
4. 如出现提示，请配置 OAuth 同意屏幕
5. 下载凭据 JSON 文件，并将其保存为项目目录中的 .gauth.json

步骤 3：配置 Google 账号

在项目目录中创建 .accounts.json 文件，指定要使用的 Google 账号：

{
  "accounts": [
    {
      "email": "[email protected]",
      "account_type": "work",
      "extra_info": "Work account with company calendar"
    },
    {
      "email": "[email protected]", 
      "account_type": "personal",
      "extra_info": "Personal account with family calendar"
    }
  ]
}

字段说明：

• email：你的 Google 账号邮箱地址
• account_type：类别，如“工作”“个人”等（便于整理）
• extra_info：额外的上下文信息，帮助 AI 理解此账号的用途

步骤 4：验证 Google 账号

准备好 .gauth.json 和 .accounts.json 文件后，为每个账号运行身份验证设置：

python auth_setup.py [email protected]
python auth_setup.py [email protected]

此脚本将自动完成 OAuth 流程，并将凭据安全地存储在 .oauth2.{email}.json 文件中。

⚠️ 安全警告：切勿将凭据文件（.gauth.json、.accounts.json、.oauth2.*.json）提交到版本控制中！请将它们添加到 .gitignore 文件，以防敏感身份验证数据意外泄露。

OAuth 2.0 权限范围（自动）

服务会自动请求以下权限——无需手动配置：

[
  "openid",
  "https://www.googleapis.com/auth/userinfo.email",
  "https://mail.google.com/",
  "https://www.googleapis.com/auth/calendar"
]

这些权限范围允许服务：

• ✅ 访问你的 Gmail（读取、发送、管理草稿）
• ✅ 管理你的 Google Calendar（创建、更新、删除事件）
• ✅ 自动创建 Google Meet 链接
• ✅ 识别你的 Google 账号

配置示例

Claude Desktop（增强版）

将以下内容添加到 Claude Desktop 配置中：

{
  "mcpServers": {
    "mcp-gsuite-enhanced": {
      "command": "uv",
      "args": [
        "--directory", 
        "/path/to/mcp-gsuite-enhanced",
        "run",
        "mcp-gsuite-enhanced"
      ]
    }
  }
}

Claude Desktop（Smithery 安装）

如果你通过 Smithery 安装，配置会自动完成！无需手动设置。

使用 uvx（增强版）

{
  "mcpServers": {
    "mcp-gsuite-enhanced": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-gsuite-enhanced",
        "run",
        "mcp-gsuite-enhanced"
      ]
    }
  }
}

增强版 Google Meet 集成

增强版会自动为新的日历事件创建 Google Meet 链接：

{
  "calendar_id": "primary",
  "summary": "Team Standup",
  "start_time": "2024-01-15T10:00:00Z",
  "end_time": "2024-01-15T10:30:00Z",
  "attendees": "[email protected],[email protected]",
  "create_meet_link": true
}

日历事件将包含：

• ✅ 自动生成的 Google Meet 链接
• ✅ 电话拨入号码
• ✅ 会议 PIN
• ✅ 邀请所有与会者

开发

设置开发环境：

git clone https://github.com/ajramos/mcp-gsuite-enhanced
cd mcp-gsuite-enhanced
uv sync
uv run mcp-gsuite-enhanced

使用 MCP Inspector 调试

由于 MCP 服务通过 stdio 运行，调试可能颇具挑战。为获得最佳调试体验，我们强烈建议使用 MCP Inspector。

你可以通过 npm 使用以下命令启动 MCP Inspector：

npx @modelcontextprotocol/inspector uv --directory /path/to/mcp-gsuite-enhanced run mcp-gsuite-enhanced

启动后，Inspector 会显示一个 URL，你可以在浏览器中访问该 URL 以开始调试。

服务日志

你也可以使用以下命令查看服务日志：

# macOS
tail -n 20 -f ~/Library/Logs/Claude/mcp-server-mcp-gsuite-enhanced.log

# Linux 
tail -n 20 -f ~/.config/Claude/logs/mcp-server-mcp-gsuite-enhanced.log

# Windows
Get-Content "$env:APPDATA\Claude\logs\mcp-server-mcp-gsuite-enhanced.log" -Wait -Tail 20

安全性

• 所有身份验证均通过 OAuth 2.0 在本地完成
• 凭据安全地存储在本地文件中
• 除 Google 的 API 外，不会向第三方发送任何数据
• 支持多个 Google 账号，各账号凭据相互隔离

致谢

基于 Markus Pfundstein 的 mcp-gsuite。

Angel Ramos 扩展了 Gmail API 的全面覆盖范围，集成了 Google Meet，并改进了功能。

鸣谢

• 原始项目：mcp-gsuite，由 Markus Pfundstein 开发（MIT License）
• Gmail 功能的设计受到社区 MCP 实现的启发，包括 Gmail-MCP-server
• 所有代码均依据 Google 官方 API 文档独立实现
• 使用 MIT 许可——未引入任何 GPL 代码

许可证

MIT License——详情请参阅 LICENSE 文件。

贡献

欢迎贡献！欢迎提交 Pull Request。

支持

如果您在使用增强功能时遇到问题：

1. 查看日志，按照上文的调试说明操作
2. 验证身份验证，运行 python auth_setup.py <your-email>
3. 提交问题，并附上：
   • 您的操作系统
   • Python 版本
   • 错误消息或日志
   • 重现问题的步骤

有关一般 MCP 问题，请参阅 Model Context Protocol 文档。