google-suite-mcp

你拥有了一个会思考的 AI。现在，给它装上双手。

这是一个开源的 Google Workspace MCP 服务器，为 Claude Desktop、Cursor、Windsurf、Zed、VS Code (GitHub Copilot)、Gemini CLI 以及任何其他模型上下文协议 (MCP) 客户端提供对 Google Sheets、Docs、Drive 和 Apps Script 的完整读写控制。82 个工具，一个服务器，MIT 许可。

google-suite-mcp 是首个 工作区操作员 (Workspace Operator)：它是唯一将 Google Workspace 视为 AI 可操作运行时的 MCP。它可以在单次调用中构建仪表板、部署 Apps Script 并格式化文档，而不是仅仅将 Workspace 作为只读表面供 AI 采样。

只需 10 分钟的 OAuth 设置即可完成所有准备工作。之后，通过简单的自然语言提示，即可构建多单元格 KPI 仪表板 (sheets_build_dashboard)、将模式转换为格式完整的表格 (sheets_build_sheet)，或将 Google Apps Script 发布为实时 Web 应用 (script_deploy)。这些是我们见过的其他 Google MCP 所不具备的三个组合原语。每个工具都经过验证：30 个端到端测试全部通过真实 Google API，而非模拟环境。 如果这里列出了某个工具，说明它已针对 Google 的生产端点执行并返回了预期结果。

MCP 是一种协议，而不是 Claude 的功能。任何支持模型上下文协议的客户端都可以使用此服务器，无论其后端使用何种模型。

不知道从哪里开始？ 将此仓库 URL 粘贴到 Claude Code、Claude Desktop、Cursor 或 ChatGPT 中，并请求它协助你安装。SETUP.md 的编写旨在让 AI 指导你完成每一步，为你打开 Google Cloud 链接，并在最后验证一切是否正常工作。

60 秒提示即可完成的操作

这些是真实的单次提示结果，而非路线图计划。一旦服务器连接成功，将以下任何内容粘贴到你的 MCP 客户端中即可。

• “在 Q4 表格中为我构建一个 KPI 仪表板，包含收入、CAC、流失率和 MRR，并进行格式化，同时应用条件颜色。” → 调用一次 sheets_build_dashboard。

• “创建一个名为 Clients 的新表格，包含这 12 列、标题样式、数据验证和冻结首行。” → 调用一次 sheets_build_sheet。

• “查找此工作簿中所有标签页中出现的 'Q3 2025'，并将其替换为 'Q4 2025'。” → 调用一次 sheets_find_replace_many。

• “创建一个绑定到此表格的 Apps Script，每周一早上 8 点给我发送摘要邮件，并将其部署为 Web 应用。” → 调用一次 script_deploy。

• “在此 Google 文档中插入一个 5 列的定价表，包含这些行。” → 调用一次 docs_insert_table。

• “在 Drive 中创建一个共享文件夹，将这三个文件移入其中，并将权限设置为任何拥有链接的人均可查看。”

• “添加条件格式，将利润率低于 15% 的行标红。”

• “保护 H 列中的公式，防止表格中的其他人编辑。”

无需代码。无需手动步骤。无需在 AI 客户端之外切换上下文。

为什么需要另一个 Google Workspace MCP 服务器？

GitHub 上大多数 Google MCP 分为两类：要么是只能查询但不能更改的只读连接器，要么是仅限 Sheets 的狭窄适配器，完全忽略了 Docs、Drive 和 Apps Script。它们只是 连接器：REST API 的薄包装器，交给 AI 后，AI 必须进行四十次工具调用并消耗大量 Token 才能完成任务。

google-suite-mcp 不是连接器。它是 操作员。其原语是 结果（构建此仪表板、部署此脚本、格式化此报告），而不是 端点（读取范围、写入单元格、列出文件）。操作员涵盖了整个套件，因为实际工作会跨越多个工具。操作员提供组合原语，因为实际工作绝不仅仅是编辑一个单元格。

它们走左边，我们走右边。

功能对比

要求

• Node.js 20 或更高版本

• 一个 Google 账号，拥有你希望 AI 操作的 Workspace 文件访问权限

• 一个 Google Cloud 项目（免费层级即可）

• OAuth 2.0 桌面凭据

• 一个兼容 MCP 的客户端：Claude Desktop、Cursor、Windsurf、Zed、VS Code (GitHub Copilot)、Gemini CLI、Cline、Goose、任何基于 OpenAI Agents SDK 构建的代理，或任何其他支持 MCP 的客户端

如果你从未接触过 Google Cloud，请预留大约 10 分钟进行首次设置。一次设置，永久使用。

如何安装 google-suite-mcp？

npm install -g google-suite-mcp

或者跳过全局安装，让你的 MCP 客户端通过 npx -y google-suite-mcp 按需获取（请参阅下方的客户端配置块）。

无论哪种方式，服务器都会将其凭据和 OAuth Token 存储在 ~/.google-suite-mcp/ 中。当你第一次运行工具时，它会准确告诉你将 Google Cloud OAuth 客户端 JSON 放在哪里，并打开浏览器进行授权。请参阅 SETUP.md 了解一次性的 Google Cloud 设置步骤。

如何连接到 Google Workspace？

这是设置中唯一需要真正关注的部分。下面的每个链接都会打开对应的 Google Cloud 控制台页面，因此你无需到处寻找。

完整指南： SETUP.md 包含按顺序排列的每个步骤，并针对常见错误提供了故障排除方法。简要步骤如下：

1. 创建 Google Cloud 项目（10 秒，免费层级）

2. 启用四个 API（点击每个链接并按“启用”）：

   • Sheets API

   • Docs API

   • Drive API

   • Apps Script API

3. 配置 OAuth 同意屏幕：选择“外部”并将你自己的 Google 邮箱添加为测试用户

4. 创建 OAuth 2.0 桌面客户端：创建凭据 > OAuth 客户端 ID > 桌面应用。复制客户端 ID 和客户端密钥。

5. 将凭据粘贴到 .env 中：

   cp .env.example .env

   然后编辑 .env 并粘贴第 4 步中的客户端 ID 和客户端密钥。

服务器首次运行工具时会打开你的浏览器，引导你完成 Google 的授权流程，并在本地缓存刷新 Token。除非你撤销访问权限，否则无需再次进行身份验证。

如果在任何步骤中遇到困难，请将 SETUP.md 粘贴到你的 AI 助手，并要求它一步步引导你完成。

如何连接我的 MCP 客户端？

每个兼容 MCP 的客户端都接受相同的两项内容：要运行的 command 和 args 列表。下面的代码块使用 npx，因此你无需管理本地安装路径。

Claude Desktop

打开你的配置文件：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

添加此条目：

{
  "mcpServers": {
    "google-suite": {
      "command": "npx",
      "args": ["-y", "google-suite-mcp"]
    }
  }
}

重启 Claude Desktop。82 个工具将出现在工具选择器中。

Cursor, Windsurf, Zed, VS Code

每个客户端都有自己的 MCP 配置位置，但接受相同的 command 和 args 格式。请查阅你客户端的 MCP 文档，并将上述代码块粘贴到其 MCP 服务器部分下。无需其他更改。

Gemini CLI

使用相同的 command 和 args 将服务器添加到你的 Gemini CLI MCP 配置（~/.gemini/config.json 或等效文件）中。

OpenAI Agents SDK

OpenAI Agents SDK（Python 和 TypeScript）原生支持 MCP 服务器。在构建代理时将 google-suite-mcp 作为 MCP 服务器传入，这 82 个工具即可供你选择的任何 OpenAI 模型使用。

任何其他 MCP 客户端

只要它支持模型上下文协议，它就能工作。无论你的客户端在哪里定义 MCP 服务器，使用相同的 command 和 args 模式即可。

使用示例

一旦服务器连接成功，你就可以像往常一样与 AI 对话。现在它有了双手。

从模式构建实时 KPI 仪表板

“在名为 'Q4 Forecast' 的工作簿中，创建一个名为 'Dashboard' 的新标签页，并构建一个包含四个单元格的 KPI 仪表板：收入、毛利率、CAC 和流失率。从 'Raw' 标签页提取值，将标题加粗，数字格式化为货币，并将低于目标的任何内容标红。”

调用一次 sheets_build_dashboard。完成。

将模式转换为表格

“创建一个名为 'Client Tracker' 的新表格，包含姓名、电子邮件、状态（下拉菜单：潜在客户 / 活跃 / 已流失）、最后联系日期（日期）和备注列。添加条件格式，使已流失的行变为红色。”

调用一次 sheets_build_sheet。完成。

编写具有真实结构的文档

“在 Docs 中起草 Henderson 项目的启动简报。包含一个利益相关者表格、一个时间线表格以及一个带有项目符号的风险部分。”

docs_insert_table 为你提供真实的表格，而不是 ASCII 模仿品。

部署 Apps Script Web 应用

“创建一个绑定到此表格的新 Apps Script 项目，添加一个返回 Summary 标签页 JSON 的 doGet，对其进行版本控制，并将其部署为我可以 curl 的 Web 应用。”

script_deploy 发布它。你将获得一个实时 URL。

重命名工作簿中每个表格的字段

“在 Expenses 工作簿中，一次性将所有表格中出现的 'customer_id' 替换为 'account_id'。”

sheets_find_replace_many 一次调用即可处理。

整理 Drive

“创建一个名为 '2026 Client Intake' 的文件夹，将我 Drive 中名称包含 'intake' 的每个文件移入其中，并将该文件夹的查看权限共享给任何拥有链接的人。”

工具列表摘要（82 个工具）

按 Google 表面分组：

• Google Sheets (53 个工具)。 创建、列出、读取、写入、追加、格式化、条件格式、图表、命名范围、受保护范围、筛选、排序、验证、边框、合并、冻结窗格、调整大小、查找/替换（单个及跨所有标签页的 sheets_find_replace_many）、搜索、公式、数组公式、批量更新、复制、重命名、重新排序、删除、sheets_build_sheet、sheets_build_dashboard。

• Google Docs (8 个工具)。 创建、写入、格式化文本、获取文本、替换文本、插入图片、docs_insert_table、导出。

• Google Drive (12 个工具)。 上传、下载、搜索、获取信息、移动、复制、重命名、移至回收站、创建文件夹、共享、列出并更新权限。

• Google Apps Script (7 个工具)。 创建、更新、获取、获取绑定、运行、创建版本、script_deploy。

• 身份验证 (2 个工具)。 状态、刷新。

每个工具都附带 Token 高效响应。每个有效负载都经过端到端审计和精简，以确保在长时间的代理运行中保持上下文窗口的精简。

如需包含实时模式的权威列表，请在连接后从任何 MCP 客户端调用 tools/list，或查看源代码树中的 src/tools/。

常见问题解答

这适用于 Cursor、Gemini CLI 或其他非 Claude MCP 客户端吗？

是的。google-suite-mcp 是一个标准的模型上下文协议服务器。任何兼容 MCP 的客户端（Claude Desktop、Cursor、Windsurf、Zed、VS Code with GitHub Copilot、Gemini CLI、Cline、Goose 或任何基于 OpenAI Agents SDK 构建的代理）都可以使用上述相同的 command 和 args 模式进行连接。请查阅你客户端的 MCP 配置文档以了解粘贴位置。MCP 是一种协议，而不是 Claude 的功能。

我可以将它与 GPT-4 或 GPT-5 等 OpenAI 模型一起使用吗？

是的。OpenAI Agents SDK 原生支持 MCP 服务器，因此你在 OpenAI 模型之上构建的任何代理都可以挂载 google-suite-mcp 并获得所有 82 个工具。服务器不关心连接的另一端是哪个模型。

我可以从 AI 部署 Apps Script 吗？

是的。google-suite-mcp 是唯一公开 script_deploy 的 MCP 服务器之一，让你的 AI 可以在不离开聊天的情况下将 Apps Script 项目发布为 Web 应用、API 可执行文件或定时触发器。你可以在单次对话中创建项目、上传源文件、进行版本控制并完成部署。

它是只读的吗？

不是。它在所有四个表面（Sheets、Docs、Drive 和 Apps Script）上都是完全读写的。每个有意义的写入工具都是可写的，包括格式化、验证、受保护范围、权限和 Apps Script 部署。

我可以自托管它吗？

是的。自托管是默认且唯一支持的配置。服务器使用你自己的 OAuth 2.0 凭据在你的机器上本地运行。没有任何数据通过第三方服务。你控制它所验证的 Google 账号，并可以随时从你的 Google 账号安全设置中撤销访问权限。

给 AI 授予 Google Drive 的写入权限安全吗？

安全模型是：你的机器、你的 OAuth 凭据、你的账号。没有任何内容发送给第三方。话虽如此，写入权限就是写入权限。在告诉 AI 继续操作之前，请务必