mcpField
G
Google Workspace MCP Server

Google Workspace MCP Server

本地服务
github.com/conorbronsdon生产力126 天前更新
代码仓库

关于 Google Workspace MCP Server

Google Workspace MCP Server 基于官方 gws CLI，将选定的 Google Workspace 服务封装为工具，供需要访问 Gmail、Drive、Calendar、Sheets 和 Docs 等服务的 Agent 使用，并支持选择服务和只读模式。

主要功能

  1. 01提供邮件、文件和文档相关工具
  2. 02选择要公开的服务
  3. 03只读模式不注册写入工具
  4. 04工具注释说明副作用
  5. 05Contacts 可作为可选服务启用

适用场景

  1. 01通过 Agent 读取 Workspace 数据
  2. 02将 MCP 配置限制为指定服务
  3. 03配置只读 Workspace 连接

MCP 相关

该服务基于官方 gws CLI，将选定的 Google Workspace 操作注册为 MCP 工具。只读模式只注册不会向 Google 写入的工具。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置
{
  "mcpServers": {
    "conorbronsdon-gws": {
      "command": "npx",
      "args": [
        "-y",
        "gws-mcp-server"
      ]
    }
  }
}
启动命令npx -y gws-mcp-server

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包
npmgws-mcp-server0.4.1

工具

61

收录的工具列表 · 更新于 2 周前

参数类型必填说明
qstring否搜索查询（例如 "name contains 'report'" 或 "mimeType='application/vnd.google-apps.folder'"）
fieldsstring否要包含的字段（例如 "files(id,name,mimeType)"）
orderBystring否排序顺序（例如 "modifiedTime desc"）
pageSizenumber否每页最大结果数（1-1000，默认 100）

详细介绍

gws-mcp-server

维护模式。 此项目已稳定，并会接收安全修复。暂无新增功能计划，但仍欢迎提交问题和拉取请求。

为 AI Agent 提供 Google Workspace：Gmail、Calendar、Drive、Sheets、Docs、Slides、Tasks 和 Contacts，作为精选的 67 个 Model Context Protocol 工具集构建，基于官方的 Google Workspace CLI (gws)。

npm version License: MIT Node Podcast X

演示：Agent 调用 calendar_events_list 工具并获取日程（示例数据）

为什么？

gws CLI 内置的 MCP 服务因暴露了 200-400 个工具、导致 MCP 客户端的上下文窗口膨胀，已在 v0.8.0 中移除。此服务采用精选方案：由你选择要开放的 Google 服务，并仅将一组精简、高价值且范围明确的操作注册为工具。每个工具都声明全部四种 MCP 注解提示——readOnlyHint、destructiveHint、idempotentHint、openWorldHint——让客户端能够判断副作用、了解哪些写入操作可以安全重试，并提供更清晰的授权提示。这是 Agent 信任基础设施中的权限环节：刻意精简的工具范围、每个工具都声明副作用，且不提供独立的发送工具——Agent 唯一能触发的外发邮件是日历邀请/更新通知；此功能需通过 sendUpdates 选择启用，默认关闭。

前提条件

  • Node.js 18+
  • 已安装并完成身份验证的 gws CLI（npm install -g @googleworkspace/cli && gws auth login）
授予少于默认值的权限范围

此服务不提供独立的发送工具——gmail_drafts_create 明确不会发送邮件，而 Agent 唯一能触发的外发邮件，是通过 sendUpdates 发送日历邀请／更新通知；该参数会经过枚举值校验，默认值为 none。gws auth login 生成的令牌权限范围比这更广。

gws auth login 会打开一个权限范围选择器，列出 九 项权限范围。默认授予 七 项：具有完整读写权限的 drive、spreadsheets、gmail.modify（Google 将其说明为“读取、撰写和发送邮件”）、calendar、documents、presentations 和 tasks——以非交互方式运行时，DEFAULT_SCOPES 也会授予这七项。

另外两项是 Cloud Pub/Sub 和 Cloud Platform，均不属于默认授予范围——gws auth login --help 将 --full 描述为“请求所有权限范围，包括 pubsub + cloud-platform”。

尚未通过实际运行选择器确认哪些项会默认勾选——上面七项是文档所述的默认授予范围，并非对 TUI 的观察结果。按 Enter 前请检查复选框，不要只相信本段说明。

因此，磁盘上的令牌可以发送邮件并改写 Drive，尽管这里的功能不会执行这些操作。请在选择器中取消选择不需要的权限范围，或者：

gws auth login --readonly    # read-only across services

根据该标志自身的帮助文本（“以逗号分隔的服务名称，用于限制权限范围选择器”），-s gmail 会将选择器限制为 Gmail。它无法加入 cloud-platform 或 pubsub，因为这两项只能通过 --full 获取。它还会替换你已有的凭据，而不是在其基础上添加权限范围。要为现有登录添加服务，请使用 gws-mcp-server auth login。

Linux 上没有密钥环，加密密钥文件与其加密的数据存放在一起。gws 仅在 macOS 和 Windows 上启用 keyring crate 的原生后端；在其他所有平台上，该依赖都不会启用任何后端，因此存储会回退到将 .encryption_key 写入 ~/.config/gws/。该文件不是存放在其他位置的密钥的备份——它本身就是密钥，而且凭据存储的文档注释明确指出，该文件永远不会被删除。在 Linux 上设置 GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=file 不会改变任何事情，因为这本来就是唯一的存储方式。在 macOS 和 Windows 上，操作系统密钥环保存密钥后，密钥文件会被删除。如果你在 Linux 上以无头模式运行，请将 ~/.config/gws/ 视为密码文件：任何能读取该目录的人都能获取凭据。

Contacts 需要默认授权范围之外的权限

people_* 工具需要 contacts 权限范围，而默认的 gws auth login（以及上文介绍的七项权限范围授权）不会请求该权限。

请使用 gws-mcp-server auth login -s people 添加 Contacts，而不要使用 gws auth login -s people。 gws 自带的筛选式登录会用筛选后的权限范围替换已保存的凭据，因此会移除你之前授予的 Drive、Gmail、Calendar 等所有权限范围（ #68，上游跟踪问题：googleworkspace/cli#673）。此服务的 auth login 则会增量授权：

gws-mcp-server auth login -s people              # keep existing scopes, add contacts
gws-mcp-server auth login -s people --dry-run    # print the gws command first

它会从 gws auth status 读取已保存凭据所持有的权限范围，添加所请求服务的权限范围，然后运行 gws auth login --scopes <existing + new>。你只需在浏览器中同意一次，之后它会再次读取 gws auth status；如果你请求的任何权限范围（旧的或新的）未获授权，例如你在 Google 的授权界面取消勾选了某个选项，它就会以非零状态码退出。gws 会保存授权界面授予的所有权限范围，因此取消勾选某个选项确实会将该权限范围从已保存的凭据中移除。在打开浏览器之前，以及之后发现缺少权限范围时，命令都会打印 gws auth login --scopes "..." 命令，以便重新请求完整列表。它需要已配置好用于 gws auth login 的客户端；如果凭据已经涵盖这些服务，则不会进行任何更改便退出。

标志效果
--services, -s <list>要添加权限范围的服务（必需）
--readonly添加每项服务的只读权限范围（已持有读写权限范围时跳过）
--dry-run打印 gws auth login 命令但不运行
--replace旧行为：仅用所请求的权限范围替换凭据
--gws-path <path>gws 二进制文件，与服务端标志相同

gws auth status 会实时发现权限范围（通过刷新令牌交换及 Google 的令牌信息查询），因此查询失败时可能缺少 scopes 字段。存在已保存凭据但无法读取其权限范围时，auth login 会拒绝继续，而不会猜测；请修复状态查询问题后重试。如果你确实要仅用所请求的权限范围重新开始，请传入 --replace。如果完全没有已保存的凭据，则这是首次登录，只会请求你指定的服务。

如果你更愿意直接运行 gws，请自行传入完整列表。对于恰好使用上文所述默认七项权限范围的凭据：

gws auth login --scopes "https://www.googleapis.com/auth/drive,https://www.googleapis.com/auth/spreadsheets,https://www.googleapis.com/auth/gmail.modify,https://www.googleapis.com/auth/calendar,https://www.googleapis.com/auth/documents,https://www.googleapis.com/auth/presentations,https://www.googleapis.com/auth/tasks,https://www.googleapis.com/auth/contacts"

还必须在你自己的 GCP 项目中启用 People API——这是 OAuth 之外的一次性步骤，因为新增权限范围授权本身不会启用新 API：

gcloud services enable people.googleapis.com --project=<your-project-id>

缺少上述任一步骤都会导致 people_* 工具失败：缺少权限范围会显示来自 Google 的 401/403 错误；API 未启用则会显示独立的 403 错误，其中会指出 API 名称，并提供用于启用它的控制台链接。

快速开始

# Install
npm install -g gws-mcp-server

# Or run from source
git clone https://github.com/conorbronsdon/gws-mcp-server.git
cd gws-mcp-server
npm install && npm run build

配置

Claude Code（.mcp.json）
{
  "mcpServers": {
    "google-workspace": {
      "command": "npx",
      "args": [
        "gws-mcp-server",
        "--services", "drive,sheets,calendar,docs,slides,gmail,tasks"
      ]
    }
  }
}

Contacts 默认不启用，因为它需要额外的身份验证和 API 设置。 完成 Contacts 的前置步骤 后， 将 people 追加到服务列表中：

"args": ["gws-mcp-server", "--services", "drive,calendar,people"]
Claude Desktop（claude_desktop_config.json）
{
  "mcpServers": {
    "google-workspace": {
      "command": "npx",
      "args": [
        "gws-mcp-server",
        "--services", "drive,sheets,calendar"
      ]
    }
  }
}

选项

标志说明默认值
--services, -s要公开的服务逗号分隔列表核心服务；people 默认不启用
--gws-pathgws 二进制文件的路径GWS_BINARY 或 gws
--read-only仅注册只读工具关闭

在 Windows 上，npm 的 gws.cmd 会被解析为其 JavaScript 入口点并通过 Node 运行。--gws-path 或 GWS_BINARY 也可以直接指向 JavaScript 入口点或 .exe。

--read-only

--read-only 注册 26 个工具，而不是默认的 61 个。所有会向 Google 写入数据的工具都不会注册，因此不会出现在 tools/list 中，Agent 也无法调用它们——包括 gmail_drafts_create，它虽然不会发送邮件，但仍属于写入操作。drive_files_download 会保留，因为它只读取数据。显式添加 people 后，总数会变为 67 个工具，其中 29 个为只读工具。

gws-mcp-server --read-only
gws-mcp-server --read-only --services drive,calendar   # combines with -s

此选项限制的是 Agent，而不是凭据。磁盘上的令牌仍保留获授的所有权限范围，机器上的其他任何程序也仍可使用它。gws auth login --readonly 才会缩小令牌的权限范围；两者互为补充。对于 MCP 服务，威胁模型针对的是 Agent，但这也是此说法的适用范围。

缩减上下文开销

每个已注册的工具都会随每次对话一同传递。默认注册表的 tools/list 载荷约为 46 KB（约 11.8K 个令牌）；选择启用 people 后，完整注册表约为 52 KB（约 13.2K 个令牌）。上面的两个标志可以组合使用，而移除整个不需要的服务是最省力的上下文优化方式：

gws-mcp-server --services calendar                       # calendar assistant: 6 tools
gws-mcp-server --services drive,docs                     # document work, nothing else
gws-mcp-server --read-only --services drive,docs,sheets  # research setup: reads only

在 .mcp.json 或 claude_desktop_config.json 中，只需编辑 args 数组即可进行同样的精简：

"args": ["gws-mcp-server", "--services", "drive,calendar"]

服务的工具数量（下方标题中的数字）反映了其上下文开销：移除 drive（24 个工具）节省最多，移除 docs（3 个工具）节省最少。目前没有逐个排除工具的标志——如果服务粒度对你的设置来说太粗，请提交问题，说明你需要怎样拆分。

可用服务和工具

drive（24 个工具）
  • drive_files_list — 搜索并列出文件
  • drive_files_get — 获取文件元数据
  • drive_files_create — 创建文件（可选上传）
  • drive_files_copy — 复制文件（适用于格式转换）
  • drive_files_update — 更新文件元数据或内容
  • drive_files_delete — 删除文件
  • drive_files_export — 将 Google Workspace 文件（文档、表格、幻灯片）导出为其他格式
  • drive_files_download — 下载文件内容（文本以内联形式返回，二进制内容以 base64 形式返回或保存到路径；Google 原生文件会导出为可读格式）
  • drive_permissions_create — 共享文件
  • drive_permissions_list — 列出文件的所有权限（审核共享状态，例如检查是否公开访问）
  • drive_permissions_update — 更改现有权限的角色（例如从读者改为写入者）；降级权限会移除相应能力。更改所有权请使用下方专用的转移工具。
  • drive_permissions_delete — 撤销文件权限
  • drive_permissions_transferOwnership — 立即将所有权转移给同一组织内的另一个 Google Workspace 账号，并将当前所有者降级为写入者；会发送强制通知邮件；不支持共享云端硬盘中的文件
  • drive_permissions_proposeOwnershipTransfer — 提议在个人/消费者账号之间转移所有权；接收方必须另行接受（会发送强制通知邮件），此操作不会直接完成转移
  • drive_comments_list — 列出文件上的评论（适用于任何 Drive 文件，不仅限于 Docs/Sheets/Slides）
  • drive_comments_get — 获取单条评论
  • drive_comments_create — 添加评论，可选择将其锚定到应用定义的区域（Workspace 编辑器仍会将其显示为未锚定）
  • drive_comments_update — 更改评论文本（仅限作者）
  • drive_comments_delete — 永久删除评论（仅限作者）
  • drive_replies_list — 列出评论的回复
  • drive_replies_get — 获取单条回复
  • drive_replies_create — 回复评论，或通过 action 字段解决/重新打开评论
  • drive_replies_update — 更改回复文本（仅限作者）
  • drive_replies_delete — 永久删除回复（仅限作者）
sheets（5 个工具）
  • sheets_get — 获取电子表格元数据
  • sheets_values_get — 读取单元格值
  • sheets_values_update — 写入单元格值
  • sheets_values_append — 追加行
  • sheets_batchUpdate — 对电子表格应用更新（条件格式、单元格／边框格式、添加工作表等；删除请求不可撤销）
calendar（6 个工具）
  • calendar_events_list — 列出日程
  • calendar_events_get — 获取日程详情
  • calendar_events_insert — 创建日程，可选填写 attendees。sendUpdates 控制邀请邮件的发送（默认值为 none，即不发送邮件；但根据参与者的设置，日程仍可能显示在其日历中）
  • calendar_events_update — 更新日程（仅更改提供的字段，但 attendees 除外；该字段会替换整个列表，未列出的参与者将被取消邀请）。支持与插入操作相同的 sendUpdates 设置
  • calendar_events_delete — 删除日程
  • calendar_freebusy_query — 查询一个或多个日历在指定时间范围内的忙闲信息
docs（3 个工具）
  • docs_get — 获取文档内容
  • docs_create — 创建文档
  • docs_batchUpdate — 应用文档更新
slides（5 个工具）
  • slides_get — 获取演示文稿的幻灯片、版式、母版和页面元素
  • slides_create — 创建空白演示文稿
  • slides_batchUpdate — 应用更新（插入／更新／删除幻灯片、文本、形状、表格等）
  • slides_pages_get — 获取单个页面（幻灯片、版式或母版）
  • slides_pages_getThumbnail — 获取页面的缩略图 URL
gmail（6 个工具）
  • gmail_messages_list — 搜索邮件
  • gmail_messages_get — 阅读邮件
  • gmail_threads_list — 搜索邮件会话
  • gmail_threads_get — 阅读完整邮件会话
  • gmail_threads_modify — 添加／移除邮件会话标签（归档、标记为已读、加星标）
  • gmail_drafts_create — 创建草稿（纯文本和／或 HTML，可通过 threadId 关联回复）。草稿不会自动发送
tasks（12 个工具）
  • tasks_tasklists_list — 列出任务清单
  • tasks_tasklists_get — 获取任务清单
  • tasks_tasklists_insert — 创建任务清单
  • tasks_tasklists_update — 更新任务清单（仅更改提供的字段）
  • tasks_tasklists_delete — 删除任务清单
  • tasks_tasks_list — 列出任务（筛选条件：已完成／已隐藏／截止日期）
  • tasks_tasks_get — 获取任务
  • tasks_tasks_insert — 创建任务（可选择嵌套或指定位置）
  • tasks_tasks_update — 更新任务（仅更改提供的字段；常见用途：标记为已完成）
  • tasks_tasks_move — 在清单内或不同清单间移动任务，或调整顺序
  • tasks_tasks_delete — 删除任务
  • tasks_tasks_clear — 隐藏清单中的所有已完成任务
people（6 个工具）

需要 contacts 权限范围并启用 People API — 请参阅 Contacts needs a scope outside the default grant。

  • people_people_get — 按资源名称获取联系人（或通过 people/me 获取已认证用户）
  • people_people_searchContacts — 按姓名、电子邮件、电话或组织搜索联系人
  • people_people_createContact — 创建新联系人
  • people_people_updateContact — 更新联系人（请求正文中必须包含当前 etag）
  • people_people_deleteContact — 永久删除联系人
  • people_connections_list — 列出已认证用户的联系人

更新语义： *_update 工具（日历日程、任务、任务清单）使用 Google API 的 patch 动词——合并提供的字段，其余字段保持不变。要清除现有值，请明确传入该值（例如空字符串），而不是省略该字段。

总计：支持 67 个工具；默认启用 61 个（旧实现中为 200-400 个）

添加新工具

编辑 src/services.ts 以添加工具定义。每个工具都直接对应一个 gws CLI 命令：

{
  name: "drive_files_list",           // MCP tool name
  description: "List files in Drive", // Shown to AI
  command: ["drive", "files", "list"],// gws CLI args
  params: [                           // Maps to --params JSON
    { name: "q", description: "Search query", type: "string", required: false },
  ],
  bodyParams: [                       // Maps to --json body
    { name: "name", description: "File name", type: "string", required: true },
  ],
}
类型化错误

工具调用失败会映射到类型化错误层级（src/errors.ts）：AuthenticationError（401/403）、RateLimitError（429）、ValidationError（400）、NotFoundError（404，drive 命令会附带共享云端硬盘访问提示）和 ServerError（5xx），它们都继承自基类 GwsError。与 HTTP API 客户端不同，此服务没有可读取状态码的响应对象——它会将 gws CLI 作为子进程启动，只能看到纯文本（stdout/stderr，或被拒绝的 Promise 的 .message）。mapGwsErrorToTyped() 会从文本中提取类似状态码的信息，同时处理原始 JSON 错误正文（Google 自身的 {"error":{"code":...,"message":...}} 格式）以及包含类似 HTTP 状态码标记的纯文本（例如 "Error 404: ..."）。如果两种格式都未找到，则原始消息会原样传递，而不会强行赋予一个臆造的状态码。

架构

MCP Client (Claude) ←→ stdio ←→ gws-mcp-server ←→ gws CLI ←→ Google APIs

该服务是一个轻量封装：它将 MCP 工具调用转换为 gws CLI 调用，在适当情况下传递 --params 和 --json，并返回 JSON 输出。身份验证由 gws CLI 负责——此服务绝不会查看或存储你的 Google 凭据。

开发

git clone https://github.com/conorbronsdon/gws-mcp-server.git
cd gws-mcp-server
npm ci
npm run lint    # type-check
npm run build
npm test        # vitest, mocks the executor layer — no real gws calls

贡献

欢迎提交问题和拉取请求。请遵循精选的服务契约：提供一组范围明确的工具，而不是逐一镜像所有 Google API。在为新服务编写 PR 之前，请先提交问题，描述使用场景、所需权限范围和副作用；docs/scope-policy.md 说明了哪些内容适合放在这里，哪些更适合作为配套服务。也欢迎直接改进现有工具。如何报告漏洞，请参阅 SECURITY.md。

配套服务

精选范围之外的服务可以作为独立 MCP 服务发布，与本服务并行运行，且各自拥有独立的权限范围授权。此处将列出社区提供的配套服务，前提是它们为每个工具声明副作用，并且不添加独立的发送操作。

其他选项

本服务刻意保持精简：精选的工具范围、每个工具都声明副作用、不提供独立的发送工具。这种取舍适合某些工作流，但不适合另一些。真正的替代方案如下：

你的需求使用
使用所有 Workspace API、可自托管，并支持分级和多用户 OAuthtaylorwilsdon/google_workspace_mcp — 涵盖 12 项服务的 120+ 个工具，MIT 许可，--tool-tier core|extended|complete
使用 Google 自己托管的服务Google Workspace remote MCP servers — 8 个端点、42 个工具。开发者预览版：需要应用、Workspace 账号（非个人 Gmail）和受支持的客户端方案
不使用 MCP——通过 CLI 和 Agent 技能实现googleworkspace/cli — 100+ 项 Agent 技能，使用的 gws auth login 与本服务相同

有一点值得直说：Google 官方的 Gmail MCP 服务同样只能起草邮件，不能发送——精选工具范围这一主张如今已不再另类。本服务仍具备而其他方案没有的功能包括：Google Tasks（Google 官方服务中没有 Tasks 服务）、每个工具都包含全部四种 MCP 注解提示、无需预览版应用或方案限制的本地 stdio 服务，以及只需一个标志即可启用的 --read-only。

数据分析领域的同类项目
数据服务
Google Workspace本仓库
Search Consolegsc-mcp — 采用同样的精选方式，包括 gsc_striking_distance 等衍生视图
YouTube Analyticsyt-analytics-mcp — 面向频道所有者的频道、视频和播放列表指标；只读，提供 9 个工具
Google Analytics 4googleanalytics/google-analytics-mcp — Google 官方项目，只读
BigQuerygoogleapis/mcp-toolbox — Google 官方项目

这些使用不同的凭据体系，而非同一个登录：Workspace 使用 gws auth login 进行身份验证，Search Console 使用 webmasters OAuth 凭据，YouTube Analytics 使用 yt-analytics.readonly OAuth 凭据，GA4 使用作用域为 analytics.readonly 的 Application Default Credentials。这里没有任何项目会与其他项目共享令牌。

关于

由 Conor Bronsdon 创建并维护。我主持 Chain of Thought 播客，探讨 AI 基础设施、开发者工具，以及从业者如何实际使用这些技术。我构建这个项目，是为了让运行节目的 Agent 工作流能够安全、精选地访问 Gmail、Calendar、Drive、Sheets、Docs、Slides、Tasks 和 Contacts。

gws-mcp-server MCP 服务

配套工具：

  • Transistor MCP：Transistor.fm 官方 MCP 服务。提供单集、发布和分析功能。
  • substack-mcp：在 Substack 上阅读帖子并管理草稿，适用于 Agent 工作流。
  • podcastindex-mcp：Podcast Index MCP 服务，可按人物或主题搜索、查看热门节目和订阅源状态。
  • op3-mcp：通过 OP3 查看播客分析数据，包括下载量、地理位置和应用。只读。
  • ai-tools-for-creators：为以创意为生的人精选的 AI 技能和 MCP 服务列表。

更多内容请访问 chainofthought.show，也可在 X 上关注。

免责声明

这是一个独立的个人项目，与任何公司均无关联，也未获得任何公司的赞助或认可。文中所有观点均为我个人观点。

许可证

MIT

评论

支持 Markdown

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。