Google Workspace MCP 是目前功能最全面的 Google 服务 MCP 服务器实现。它将 Google 全家桶的 12 项服务封装为标准化 MCP 工具，让 Claude Code 可以通过自然语言对话直接操控 Gmail、Google Drive、Calendar、Docs、Sheets 等主流服务。
该 MCP 服务器由社区开发者 taylorwilsdon 创建并维护，基于 FastMCP 框架构建，在 GitHub 上拥有 2000+ Star。它已发布为 workspace-mcp Python 包，可通过 uvx 一键启动。项目采用 MIT 开源协议，无遥测、无 SaaS 依赖、无外部数据传输路径。
Google Workspace MCP 将工具分为三个层级，方便用户按需加载：
推荐大多数用户使用 Core 层级启动，既满足日常需求，又避免注册过多工具导致 Claude Code 上下文窗口膨胀。当需要特定高级功能时，再升级到 Extended 或 Complete 层级。
在使用 Google Workspace MCP 之前，需要先完成 Google Cloud 项目的配置。这是整个过程中最关键的步骤。
根据你打算使用的服务，在 API 和服务 > 库 中搜索并启用对应的 API：
| 服务 | 需启用的 API 名称 |
|---|---|
| Gmail | Gmail API |
| Google Drive | Google Drive API |
| Calendar | Google Calendar API |
| Docs | Google Docs API |
| Sheets | Google Sheets API |
| Slides | Google Slides API |
| Forms | Google Forms API |
| Chat | Google Chat API |
| Tasks | Google Tasks API |
| Contacts | People API |
| Apps Script | Apps Script API |
| Search | Custom Search API |
新创建的 OAuth 应用默认处于"测试中"状态，颁发的 token 有效期为 7 天。如果需要长期使用且不想频繁重新认证，可以：
workspace-mcp 通过 uvx 启动，因此需要先安装 uv 工具：
第一次启动时，浏览器会自动打开 Google OAuth 授权页面。登录你的 Google 账号并授予相应权限。授权成功后，token 会保存在本地文件中（默认位置：~/.google_workspace_mcp/credentials/）。后续启动将自动复用已保存的 token，不再需要浏览器授权。
有两种方式将 MCP 服务器注册到 Claude Code：
list_calendars 和 get_events 工具返回结果。
以下按服务分类，详细介绍每个工具的用途和所属层级。
覆盖邮件搜索、读取、发送、标签管理等核心操作。
| 工具名称 | 功能说明 | 层级 |
|---|---|---|
| search_gmail_messages | 搜索邮件，支持 Gmail 搜索语法和分页 | Core |
| get_gmail_message_content | 获取单封邮件的完整内容（含正文和附件信息） | Core |
| get_gmail_messages_content_batch | 批量获取多封邮件内容 | Core |
| send_gmail_message | 发送新邮件，需二次确认 | Core |
| get_gmail_thread_content | 获取完整邮件线程（含所有回复） | Extended |
| modify_gmail_message_labels | 修改邮件的标签（添加/移除） | Extended |
| list_gmail_labels | 列出所有 Gmail 标签 | Extended |
| manage_gmail_label | 创建、更新、删除标签 | Extended |
| draft_gmail_message | 创建和更新邮件草稿 | Extended |
| get_gmail_threads_content_batch | 批量获取多个线程内容 | Complete |
| batch_modify_gmail_message_labels | 批量修改多封邮件的标签 | Complete |
管理云端文件，包括搜索、创建、共享和权限控制。
| 工具名称 | 功能说明 | 层级 |
|---|---|---|
| search_drive_files | 搜索云端文件，支持类型和关键词筛选 | Core |
| get_drive_file_content | 读取文件内容（文本/PDF/Office 文档等） | Core |
| get_drive_file_download_url | 获取文件下载链接 | Core |
| create_drive_file | 创建新文件（上传本地文件到云端） | Core |
| share_drive_file | 共享文件给指定用户并设置权限 | Core |
| get_drive_shareable_link | 获取文件的可共享链接 | Core |
| list_drive_items | 列出指定文件夹中的文件列表 | Extended |
| update_drive_file | 更新文件的元数据（名称、描述等） | Extended |
| batch_share_drive_file | 批量共享文件给多个用户 | Extended |
| update_drive_permission | 更新已存在的共享权限 | Extended |
| remove_drive_permission | 移除用户的文件访问权限 | Extended |
| transfer_drive_ownership | 转移文件所有权给其他用户 | Extended |
| get_drive_file_permissions | 查看文件的所有权限设置 | Complete |
| check_drive_file_public_access | 检查文件是否有公开访问权限 | Complete |
管理日程和日历事件。
| 工具名称 | 功能说明 | 层级 |
|---|---|---|
| list_calendars | 列出用户的所有日历 | Core |
| get_events | 获取日历中的事件列表，支持时间范围过滤 | Core |
| create_event | 创建新日历事件（含标题、时间、参与人、地点） | Core |
| modify_event | 修改已有事件 | Core |
| delete_event | 删除指定事件 | Extended |
创建、编辑和管理在线文档。
| 工具名称 | 功能说明 | 层级 |
|---|---|---|
| get_doc_content | 读取文档内容 | Core |
| create_doc | 创建新文档 | Core |
| modify_doc_text | 修改文档中的文本内容 | Core |
| search_docs | 搜索文档 | Extended |
| find_and_replace_doc | 在文档中查找替换文本 | Extended |
| list_docs_in_folder | 列出指定文件夹中的文档 | Extended |
| insert_doc_elements | 插入段落、列表、表格等元素 | Extended |
| export_doc_to_pdf | 将文档导出为 PDF | Extended |
| insert_doc_image | 插入图片到文档 | Complete |
| update_doc_headers_footers | 更新页眉页脚 | Complete |
| batch_update_doc | 批量更新文档 | Complete |
| inspect_doc_structure | 检查文档结构 | Complete |
| create_table_with_data | 在文档中创建数据表格 | Complete |
| read_doc_comments | 读取文档评论 | Complete |
| create_doc_comment | 创建评论 | Complete |
| reply_to_comment | 回复评论 | Complete |
| resolve_comment | 解决/关闭评论 | Complete |
读写电子表格数据，管理表格结构。
| 工具名称 | 功能说明 | 层级 |
|---|---|---|
| read_sheet_values | 读取指定范围的数据 | Core |
| modify_sheet_values | 修改单元格数据 | Core |
| create_spreadsheet | 创建新的电子表格 | Core |
| list_spreadsheets | 列出电子表格 | Extended |
| get_spreadsheet_info | 获取表格的元数据信息 | Extended |
| create_sheet | 在表格中创建工作表 | Complete |
| read_sheet_comments | 读取表格评论 | Complete |
| create_sheet_comment | 创建表格评论 | Complete |
| reply_to_sheet_comment | 回复表格评论 | Complete |
| resolve_sheet_comment | 解决表格评论 | Complete |
创建和编辑演示文稿。
| 工具名称 | 功能说明 | 层级 |
|---|---|---|
| create_presentation | 创建新演示文稿 | Core |
| get_presentation | 获取演示文稿内容 | Core |
| batch_update_presentation | 批量更新幻灯片 | Extended |
| get_page | 获取指定页面内容 | Extended |
| get_page_thumbnail | 获取页面缩略图 | Extended |
| read_presentation_comments | 读取演示文稿评论 | Complete |
| create_presentation_comment | 创建评论 | Complete |
| reply_to_presentation_comment | 回复评论 | Complete |
| resolve_presentation_comment | 解决评论 | Complete |
| 工具名称 | 功能说明 | 层级 |
|---|---|---|
| create_form | 创建新表单 | Core |
| get_form | 获取表单内容 | Core |
| list_form_responses | 列出表单回复 | Extended |
| get_form_response | 获取单个回复详情 | Complete |
| set_publish_settings | 设置发布配置 | Complete |
| 工具名称 | 功能说明 | 层级 |
|---|---|---|
| get_messages | 获取空间中的消息 | Core |
| send_message | 向空间发送消息 | Core |
| search_messages | 搜索聊天消息 | Core |
| list_spaces | 列出所有聊天空间 | Extended |
| 工具名称 | 功能说明 | 层级 |
|---|---|---|
| list_tasks / get_task / create_task / update_task | 任务的增删改查 | Core |
| delete_task / move_task / clear_completed_tasks | 删除、移动、清除已完成任务 | Extended / Complete |
| list_task_lists / get_task_list / create_task_list / update_task_list / delete_task_list | 任务列表管理 | Complete |
search_custom、search_custom_siterestrict、get_search_engine_info）对于安全敏感场景，可以使用只读模式启动，禁止任何修改操作：
只读模式下，所有涉及写入的操作（发送邮件、创建文件、修改事件等）都会被禁用。适合审计、合规严格的场景。
可以按服务和操作类型细分权限：
适用于服务器环境和团队共享：
适用于组织或多人协作场景，每个用户独立认证：
| 环境变量 | 用途 | 默认值 |
|---|---|---|
| GOOGLE_OAUTH_CLIENT_ID | OAuth 客户端 ID（必填） | — |
| GOOGLE_OAUTH_CLIENT_SECRET | OAuth 客户端密钥 | — |
| MCP_ENABLE_OAUTH21 | 启用 OAuth 2.1 多用户支持 | false |
| WORKSPACE_MCP_PORT | HTTP 服务监听端口 | 8000 |
| WORKSPACE_MCP_HOST | HTTP 服务绑定地址 | 0.0.0.0 |
| WORKSPACE_EXTERNAL_URL | 反向代理外部 URL | — |
| WORKSPACE_MCP_STATELESS_MODE | 容器模式无磁盘写入 | false |
| ALLOWED_FILE_DIRS | 允许读取的本地文件目录（冒号分隔） | — |
| WORKSPACE_MCP_CREDENTIAL_STORE_BACKEND | 凭据存储后端（local_directory/gcs） | local_directory |
| WORKSPACE_MCP_OAUTH_PROXY_STORAGE_BACKEND | OAuth 代理存储后端（memory/disk/valkey） | disk |
当同时运行多个 Claude Code 会话时，每个会话都会尝试启动自己的 MCP 服务器进程，导致 OAuth 凭据冲突和资源浪费。Coogle 通过守护进程模式优雅地解决了这个问题。
Coogle 是一个 MCP 多路复用器（Multiplexer），其架构如下：
/tmp/coogle.sock）连接到守护进程如果你只是偶尔使用 Claude Code 操作 Google 服务，不需要 Coogle。但如果你：
在这些情况下，Coogle 可以避免烦人的"凭据冲突"错误。
针对对安全性有更高要求的企业环境，社区提供了安全加固版本的 Google Workspace MCP。该版本专门针对提示词注入攻击做防护。
| 安全维度 | 加固版行为 | 原版行为 |
|---|---|---|
| 邮件发送 | 禁止发送，仅允许创建草稿 | 允许发送（需确认） |
| 文件分享 | 禁止分享给外部用户 | 允许分享 |
| 自动转发 | 禁止设置转发规则 | 允许设置 |
| 凭据存储 | macOS Keychain 加密存储 | 文件系统明文存储 |
| 工具数量 | 精简到最小值 | 完整工具集 |
以下展示通过 Google Workspace MCP 操作各个服务的典型对话场景。所有操作均通过自然语言在 Claude Code 中完成。
用户："帮我查一下收件箱中来自张三的最新邮件"
Claude Code：调用 search_gmail_messages(query: "from:zhangsan@company.com") → 获取最新结果 → 显示邮件摘要
用户："把昨天那封关于项目进度的邮件标记为重要，并归档"
Claude Code：搜索匹配邮件 → 调用 modify_gmail_message_labels 添加 STARED 标签 → 移除 INBOX 标签
用户："帮我找一下 Drive 里上个月的产品设计文档"
Claude Code：调用 search_drive_files(query: "产品设计") → 按时间排序 → 显示结果
用户："把这份季度报告分享给整个团队，设置只读权限"
Claude Code：调用 share_drive_file → 添加团队成员 → 设置 reader 角色
用户："今天下午3点安排一个团队周会，邀请小王和小李参加"
Claude Code：调用 list_calendars → 调用 create_event(title="团队周会", time="15:00-16:00", attendees=["小王","小李"]) → 返回创建结果
用户："这周有哪些会议？帮我列出来"
Claude Code：调用 get_events(timeMin="周一", timeMax="周日") → 按日期组织结果 → 展示
用户："创建一份新文档，标题是'项目计划 v2'，内容包含项目背景、时间规划和负责人"
Claude Code：调用 create_doc(title="项目计划 v2") → 调用 modify_doc_text 写入内容 → 返回文档链接
用户："在需求文档中帮我查找替换，把'旧系统'替换成'新平台'"
Claude Code：调用 find_and_replace_doc → 执行替换 → 返回替换数量
用户："创建一个新的销售数据表，包含产品名、销量和收入三列，填入示例数据"
Claude Code：调用 create_spreadsheet → 调用 modify_sheet_values 写入标题和数据 → 返回链接
用户："把今天需要处理的所有任务整理成一份文档，放到项目文件夹里"
Claude Code：调用 list_tasks → 获取任务列表 → 调用 create_doc 创建文档 → 调用 search_drive_files 找到项目文件夹 → 移动文档到目标位置
| 对比维度 | Google Workspace MCP | gmail-multi-mcp | gmail-autoauth-mcp |
|---|---|---|---|
| 服务覆盖 | 12 项 Google 服务 | 仅 Gmail | 仅 Gmail |
| 工具数量 | 100+（可选层级） | 6 个 | 约 10 个 |
| 配置复杂度 | 中等（需 Google Cloud） | 低（零配置） | 中低 |
| 多账号 | 支持（OAuth 2.1） | 原生多账号 | 单账号 |
| Docker 部署 | 支持 | 不支持 | 不支持 |
| 只读模式 | 支持 | 不支持 | 通过 scope 限制 |
| 适用场景 | 需要 Google 全家桶集成 | 仅需快速操作 Gmail | 精细控制 Gmail 权限 |
| 对比维度 | Google Workspace MCP | Python + Gmail API |
|---|---|---|
| 交互方式 | 自然语言对话 | 编写运行 Python 脚本 |
| 实时性 | 对话中即时返回 | 需等待脚本执行 |
| 跨服务编排 | 天然支持（Gmail+Drive+Calendar 等） | 需要自行编写胶水代码 |
| 自动化能力 | 依赖用户主动发起 | 可配置定时任务 |
| 工具覆盖面 | 100+ 标准化工具 | 自由调用全部 API |
| 学习成本 | 低（配置一次即可） | 中（需了解 API 和编程） |
| 适用场景 | 日常办公、快速查询 | 批量处理、复杂工作流 |
三者不是互斥关系，而是互补关系：
~/.google_workspace_mcp/credentials/，确保该目录权限正确--tool-tier core 而非 complete，只暴露必要的工具--read-only 模式--permissions 参数按服务细分权限--tool-tier core 减少攻击面| 问题 | 原因 | 解决方案 |
|---|---|---|
| uvx 命令找不到 | 未安装 uv 工具 | 运行官方安装脚本安装 uv |
| OAuth 认证页面不弹出 | 环境变量未设置或浏览器拦截 | 检查 GOOGLE_OAUTH_CLIENT_ID 是否设置正确；关闭弹窗拦截器 |
| token 过期频繁（7天） | OAuth 应用处于"测试中"状态 | 在 OAuth 同意屏幕中发布应用，或使用 Workspace 内部应用 |
| Too many tools registered | 加载了过多工具超出客户端限制 | 使用 --tool-tier core 或 --tools 精确指定需要加载的服务 |
| API not found 错误 | 对应的 Google API 未启用 | 在 Cloud Console 中搜索并启用对应的 API |
| MCP server disconnected | 进程意外退出或端口冲突 | 检查端口占用；重新启动 MCP 服务器；重启 Claude Code |
| Windows 上认证失败 | gws auth 在 Windows 上已知有问题 | 直接通过 Cloud Console 配置 OAuth，使用环境变量传递凭据 |
| Docker 中 token 不持久化 | 容器重启后 token 丢失 | 使用 volume 挂载凭据目录，或设置 WORKSPACE_MCP_CREDENTIAL_STORE_BACKEND=gcs |
| 反向代理下认证回调失败 | 回调 URL 不匹配 | 设置 WORKSPACE_EXTERNAL_URL 为正确的代理外部 URL |
| Coogle 无法连接 | 守护进程未启动 | 先运行 node dist/index.js setup 启动守护进程 |
claude mcp add，完成即可使用。