Google Workspace MCP Server

Google Workspace MCP 服务器

这款模型上下文协议 (MCP) 服务器让您掌控自己的 Google Workspace。只需一分钟，即可轻松连接您的帐号，安全可靠。它会在后台确保您的连接安全且活跃，让您专注于完成工作，无需管理登录名和权限。

以您意想不到的方式掌控您的 Gmail 收件箱。想要上季度的提案？几秒钟内即可找到。新闻简报堆积如山？它们会自动分类归入文件夹。需要追踪重要主题的回复？标签和过滤器可为您完成所有工作。从撰写完美的电子邮件到管理与团队的对话，一切都轻而易举。借助简化的附件处理功能，您可以轻松查找和管理电子邮件附件，而系统会在后台处理所有复杂的元数据。

您的日历将成为您日常事务中值得信赖的助手。不再有重复预订的会议或时区混乱的情况。计划团队同步？它能帮您找到最合适的时间段。举办定期研讨会？只需设置一次，即可轻松搞定。即使计划有变，也能快速轻松地找到适合所有人的新时间。无休止地收到“您什么时候有空？”邮件的日子已经一去不复返了。

将 Google Drive 从文件转储变成您的数字指挥中心。每个文档都各归其位，每个文件夹都讲述着一个故事。与合适的人共享文件 - 不再需要“谁可以编辑这个文件？”的困惑。正在寻找上周会议的演示文稿？不仅搜索名称，还可以搜索文件内容。无论您是在组织小型项目还是管理海量文档，所有内容都能轻松找到。

TL;DR 设置

注意：对于像 Cline 这样的 AI 助手，请参阅llms-install.md获取专门的安装指南。

1. 创建 Google Cloud 项目：
   # Go to Google Cloud Console https://console.cloud.google.com → Create Project → Enable Gmail API and Calendar API → Configure OAuth consent screen (External) → Create OAuth Desktop Client ID and Secret
2. 添加到 Cline 设置（例如， ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json ）：
   { "mcpServers": { "google-workspace-mcp": { "command": "docker", "args": [ "run", "--rm", "-i", "-v", "/home/aaron/.mcp/google-workspace-mcp:/app/config", "-v", "/home/aaron/Documents/workspace-mcp-files:/app/workspace", "-e", "GOOGLE_CLIENT_ID", "-e", "GOOGLE_CLIENT_SECRET", "-e", "LOG_MODE=strict", "ghcr.io/aaronsb/google-workspace-mcp:latest" ], "env": { "GOOGLE_CLIENT_ID": "123456789012-abcdef3gh1jklmn2pqrs4uvw5xyz6789.apps.googleusercontent.com", "GOOGLE_CLIENT_SECRET": "GOCSPX-abcdefghijklmnopqrstuvwxyz1234" }, "autoApprove": [], "disabled": false } } }
   日志记录模式：
   • normal （默认）：针对每个日志级别使用适当的控制台方法
   • strict ：将所有非 JSON-RPC 消息路由到 stderr（推荐用于 Claude 桌面）
3. 重启克莱恩/克劳德
4. 只需要求 AI“添加我的 Google 帐户” - 它就会以对话的方式指导您完成身份验证过程。

请参阅详细的设置指南以了解更多信息。

先决条件

重要的：
在启动 MCP 服务器之前，您必须自行创建配置目录（例如~/.mcp/google-workspace-mcp ），并确保它归您的用户帐户所有。
如果此目录丢失或由 root 拥有，服务器将无法创建或更新配置文件，并且无法启动。

在使用此 MCP 服务器之前，您必须设置自己的 Google Cloud 项目并访问 Google Workspace API：

1. 在Google Cloud Console中创建新项目
2. 启用所需的 API：
   • Gmail API
   • Google 日历 API
   • Google Drive API
3. 配置 OAuth 同意屏幕：
   • 设置为“外部”
   • 将自己添加为测试用户
   • 添加 Gmail、日历和云端硬盘所需的范围
4. 创建 OAuth 2.0 凭据：
   • 选择“桌面应用程序”类型
   • 记下您的客户端 ID 和客户端密钥
   • 使用“urn:2.0”作为重定向 URI（这可启用带外身份验证）

MCP 服务器需要：

1. 您在以上步骤中获取的 Google OAuth 客户端 ID 和密钥
2. 存储配置的本地目录路径（推荐： ~/.mcp/google-workspace-mcp ）

注意：此服务器使用带外（OOB）身份验证流程，这意味着您需要在每个帐户的初始设置期间手动复制粘贴授权码。

与 Cline 一起使用

将以下配置添加到您的 Cline MCP 设置：

文件管理

服务器以结构化的方式自动管理文件：

WorkspaceManager 自动创建并维护此结构：

• 下载/上传文件时根据需要创建目录
• 按用户电子邮件组织文件
• 处理临时文件清理
• 维护适当的权限

您可以通过设置WORKSPACE_BASE_PATH环境变量来自定义工作区位置。

手动使用

重要的：
在启动容器之前，您挂载的配置目录（例如~/.mcp/google-workspace-mcp ）必须存在并且归您的用户所有。
如果不存在，请使用mkdir -p ~/.mcp/google-workspace-mcp && chown $USER ~/.mcp/google-workspace-mcp创建。
如果缺少accounts.json服务器将尝试自动创建，但前提是它对该目录具有写权限。

您可以直接运行容器：

服务器将自动：

• 创建和管理所有必要的配置文件
• 处理凭证和令牌的安全存储
• 维护适当的文件权限

开发构建

本地构建脚本

为了快速、类似 CI 的本地构建和 Docker 镜像创建，请使用提供的脚本：

• 默认情况下，该图像被标记为google-workspace-mcp:local 。
• 要使用详细输出（将所有日志打印到控制台），请添加--verbose ：
  ./scripts/build-local.sh --verbose
• 要更改 Docker 镜像标签：
  ./scripts/build-local.sh --tag my-custom-tag
• 日志文件写入/tmp/google-workspace-mcp/以供审查。

构建脚本使用Dockerfile.local ，该文件针对本地开发进行了优化，无需特定于平台的设置或 BuildKit 功能。这确保了跨不同开发环境的兼容性。

手动 Docker 构建

您还可以手动构建并运行容器：

特征

• 通过自动元数据管理简化附件处理
• 简化的电子邮件回复，重点关注重要信息
• 强大的附件索引和检索系统
• 跨 Gmail 和日历的高效文件管理
• 自动清理过期附件

可用工具

账户管理

• list_workspace_accounts （别名：list_accounts、get_accounts、show_accounts）
  • 列出所有已配置的 Google 帐户和身份验证状态
  • 必须在其他操作之前先调用
  • 验证所需的 API 范围
  • 处理多个帐户选择
• authenticate_workspace_account （别名：auth_account、add_account、connect_account）
  • 添加并验证 Google 帐户以进行 API 访问
  • 支持账户分类（工作、个人）
  • 处理与用户交互的 OAuth 流程
  • 自动管理令牌刷新
• remove_workspace_account （别名：delete_account、disconnect_account、remove_account）
  • 删除 Google 帐户和相关令牌
  • 清理存储的凭据

Gmail操作

消息和搜索

• search_workspace_emails （别名：search_emails、find_emails、query_emails）
  • 高级电子邮件过滤功能：
    • 发件人/收件人筛选
    • 主题和内容搜索
    • 日期范围过滤
    • 附件存在
    • 基于标签的过滤
    • 复杂的 Gmail 查询语法支持
  • 常见搜索模式：
    • 会议电子邮件
    • 人力资源/行政沟通
    • 团队更新
    • 时事通讯
• send_workspace_email （别名：send_email、send_mail、create_email）
  • 发送完整格式的电子邮件
  • 支持抄送/密送收件人
  • 附件处理
  • 电子邮件线程支持

设置和配置

• get_workspace_gmail_settings （别名：get_gmail_settings、gmail_settings、get_mail_settings）
  • 访问帐户设置
  • 语言偏好
  • 签名配置
  • 休假响应者状态
  • 过滤和转发规则

草稿管理

• manage_workspace_draft （别名：manage_draft、draft_operation、handle_draft）
  • 完成草稿 CRUD 操作：
    • 创建新草稿
    • 阅读现有草稿
    • 更新草稿内容
    • 删除草稿
    • 发送草稿
  • 支持：
    • 新的电子邮件草稿
    • 使用主题回复草稿
    • 修改草案
    • 发送草稿

标签管理

• manage_workspace_label （别名：manage_label、label_operation、handle_label）
  • 全标签CRUD操作
  • 支持嵌套标签
  • 自定义颜色配置
  • 可见性设置
• manage_workspace_label_assignment （别名：assign_label、modify_message_labels、change_message_labels）
  • 在邮件中应用/删除标签
  • 批次标签修改
  • 系统标签更新
• manage_workspace_label_filter （别名：manage_filter、handle_filter、filter_operation）
  • 创建和管理标注过滤器
  • 复杂的过滤条件：
    • 发送者/接收者模式
    • 主题/内容匹配
    • 附件存在
    • 邮件大小规则
  • 自动化操作：
    • 标签应用
    • 重要性标记
    • 已读状态
    • 归档

日历操作

活动管理

• list_workspace_calendar_events （别名：list_events、get_events、show_events）
  • 通过筛选列出日历事件
  • 日期范围规范
  • 事件内的文本搜索
  • 可定制的结果限制
• get_workspace_calendar_event （别名：get_event、view_event、show_event）
  • 详细活动信息
  • 参会者状态
  • 事件设置
• manage_workspace_calendar_event （别名：manage_event、update_event、respond_to_event）
  • 事件响应管理：
    • 接受/拒绝邀请
    • 标记为暂定
    • 提出新的时代
    • 更新活动时间
  • 评论支持
  • 时区处理
• create_workspace_calendar_event （别名：create_event、new_event、schedule_event）
  • 创建新的日历事件
  • 支持：
    • 单项赛事
    • 重复事件（RRULE 格式）
    • 多名与会者
    • 时区规范
    • 事件描述
    • 冲突检查
• delete_workspace_calendar_event （别名：delete_event、remove_event、cancel_event）
  • 删除日历事件
  • 与会者的通知选项

联系方式 运营

• get_workspace_contacts （别名：get_contacts、list_contacts、fetch_contacts）
  • 从 Google 帐户检索联系人
  • 支持：
    • 基本联系信息（姓名、电子邮件、电话）
    • 详细联系方式
    • 大型联系人列表的分页
  • 常见用例：
    • 联系人查找
    • 地址簿管理
    • 联系信息检索

驱动操作

文件管理

• list_drive_files （别名：list_files、get_files、show_files）
  • 列出具有可选过滤功能的文件
  • 按文件夹过滤
  • 自定义查询支持
  • 排序和分页
  • 字段选择
• search_drive_files （别名：search_files、find_files、query_files）
  • 跨文件内容的全文搜索
  • 按 MIME 类型过滤
  • 按文件夹过滤
  • 包含/排除已删除的文件
  • 高级查询选项
• upload_drive_file （别名：upload_file、create_file、add_file）
  • 上传新文件
  • 设置文件元数据
  • 指定父文件夹
  • 支持各种文件类型
• download_drive_file （别名：download_file、get_file_content、fetch_file）
  • 下载任何文件类型
  • 导出 Google Workspace 文件
  • 格式转换选项
  • 自动 MIME 类型处理
• delete_drive_file （别名：delete_file、remove_file、trash_file）
  • 删除文件和文件夹
  • 从驱动器中彻底删除

文件夹操作

• create_drive_folder （别名：create_folder、new_folder、add_folder）
  • 创建新文件夹
  • 嵌套文件夹支持
  • 父文件夹规范
  • 文件夹元数据

权限

• update_drive_permissions （别名：share_file、update_sharing、modify_permissions）
  • 更新共享设置
  • 多种权限类型：
    • 用户权限
    • 组权限
    • 域名共享
    • 公共访问
  • 各种访问角色：
    • 所有者
    • 组织者
    • 文件管理器
    • 作家
    • 评论者
    • 读者
  • 公共文件的发现设置

详细使用方法请参见API 文档。

即将推出

未来服务

• Admin SDK 支持
• 其他 Google 服务

测试策略

单元测试方法

1. 简化模拟
   • 使用静态模拟响应进行可预测的测试
   • 避免在单元测试中进行复杂的端到端模拟
   • 专注于一次测试一项功能
   • 通过简单的实现模拟外部依赖关系（OAuth、文件系统）
2. 测试组织
   • 按功能对测试进行分组（例如，帐户操作、文件操作）
   • 使用清晰、描述性的测试名称
   • 保持测试集中且独立
   • 在测试之间重置模拟和模块
3. 模拟管理
   • 使用 jest.resetModules() 来确保清洁状态
   • 模拟更改后重新要求模块
   • 明确跟踪模拟函数调用
   • 验证函数调用和结果
4. 文件系统测试
   • 使用简单的 JSON 结构
   • 关注数据正确性而非格式
   • 测试错误场景（缺少文件、无效 JSON）
   • 验证文件操作而无需执行细节
5. 令牌处理
   • 使用静态响应模拟令牌验证
   • 分别测试成功和失败的情况
   • 无需 OAuth 复杂性即可验证令牌操作
   • 关注账户经理的代币处理逻辑

运行测试

最佳实践

1. 验证
   • 在 MCP 设置中安全地存储凭据
   • 使用最小要求范围
   • 正确处理令牌刷新
2. 错误处理
   • 检查响应状态
   • 适当处理授权错误
   • 实施适当的重试
3. 配置和安全
   • 每个用户维护自己的 Google Cloud 项目
   • 在 MCP 设置中配置 OAuth 凭据
   • 在 ~/.mcp/google-workspace-mcp 中安全存储令牌
   • 定期代币轮换
   • 切勿将敏感文件提交给 git
   • 对配置目录使用适当的文件权限
4. 本地开发设置
   • 在 MCP 设置中配置 OAuth 凭据
   • 创建 ~/.mcp/google-workspace-mcp 目录
   • 将敏感令牌置于版本控制之外
   • 为每个帐户运行身份验证脚本

故障排除

常见设置问题

1. 缺少配置
   • 错误：“需要 GOOGLE_CLIENT_ID 环境变量”
   • 解决方案：在 MCP 设置文件中配置 OAuth 凭据（有关详细信息，请参阅 docs/API.md）
2. 身份验证错误
   • 错误：“无效的 OAuth 凭据”
   • 解决方案：
     • 验证您的 Google Cloud 项目是否已正确配置
     • 确保您已在 OAuth 同意屏幕中将自己添加为测试用户
     • 检查 Gmail API 和 Google Calendar API 是否已启用
     • 验证 MCP 设置中的凭据是否与 OAuth 客户端配置相匹配
3. 代币问题
   • 错误：“令牌刷新失败”
   • 解决方案：使用remove_workspace_account删除该帐户并重新进行身份验证
   • 检查您的 Google Cloud 项目是否已启用必要的 API 范围
4. 目录结构
   • 错误：“未找到目录”
   • 解决方案：确保 ~/.mcp/google-workspace-mcp 存在且具有适当的权限
   • 验证 Docker 是否有权挂载配置目录

如需更多帮助，请参阅错误处理文档。

执照

MIT 许可证 - 详情请参阅许可证文件