Google Apps Script MCP

Google Apps Script MCP

中文 | Русский

A1 Google Apps Script MCP 让 AI 应用能够通过自然语言编写和操作 Google Apps Script。创建脚本项目、读取和编辑代码、创建版本快照、管理部署、运行函数并查看执行历史。

它通过你的 Google 账号使用 Google Apps Script API。它区分可编辑的 HEAD 代码与不可变版本，并明确说明 Apps Script API 的限制，而不会暗示所有脚本任务都能完成。

• 19 个工具。 创建独立项目和绑定项目、读取和更新代码文件、创建不可变版本快照、管理部署、运行函数，以及检查执行历史和指标。
• 直接在对话中连接。 说“连接 Google Apps Script”：服务会引导你设置 OAuth 客户端，使用 PKCE 捕获 Google 重定向到 127.0.0.1 的请求，并自行保管令牌——无需配置文件，也无需重启。
• 版本不可变。 版本会对 HEAD 创建快照，且永远无法编辑或删除；部署指向版本，因此你可以发布和回滚，而无需更改 URL。
• 清单始终保留。 合并模式会保留 appsscript 清单和所有未提及的文件；替换模式会在任何网络请求发出前，拒绝不包含清单的文件集。
• 保留你的 scriptId。 API 无法列出项目，也无法删除项目——create_project 返回的 scriptId 是唯一的标识。
• 尽量精简 Google 权限范围。 每项操作都会注明自己的权限范围（script.projects、script.deployments、script.processes、script.metrics）；只请求任务所需的权限。

从只读问题开始：

显示我的 report 脚本中的文件，以及本周执行失败的函数。

连接服务 · 探索使用场景 · 查看技术文档

一分钟了解它的工作方式

你： 显示我的 report 脚本代码和最近的运行记录。

助手： 显示所有文件及其源代码和执行历史记录——运行过哪些函数、运行时间，以及哪些函数运行失败。一切都不会改变。

你： 在 Utils 文件中添加一个 formatDate 辅助函数，其他内容保持不变。

助手： 显示拟议的源代码，并确认合并模式不会改动其他文件，然后在写入前请求确认。

你： 确认。

助手： 将文件写入 HEAD。除非你另行提出要求，否则不会创建版本、重新部署或运行任何内容。

目录

• 快速开始
• 你可以让它做什么
• 项目如何变更
• 哪些内容可以变更
• 获取访问权限
• 配置
• 数据、限制和后台工作
• 技术文档
• 支持

快速开始

你需要 Node.js 20+ 和一个 Google 账号。安装时无需凭据——服务会在对话过程中连接。

1. 将服务添加到 AI 应用中。
2. 说“连接 Google Apps Script”：助手会引导你创建 OAuth 客户端并批准访问，无需编辑配置文件。
3. 提出上面那个只读问题。

codex mcp add google-apps-script \
  -- npx -y mcp-google-apps-script@latest

codex mcp list

claude mcp add \
  --transport stdio --scope user google-apps-script \
  -- npx -y mcp-google-apps-script@latest

claude mcp list

{
  "mcpServers": {
    "google-apps-script": {
      "command": "npx",
      "args": ["-y", "mcp-google-apps-script@latest"]
    }
  }
}

{
  "mcpServers": {
    "google-apps-script": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-google-apps-script@latest"]
    }
  }
}

{
  "servers": {
    "google-apps-script": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-google-apps-script@latest"]
    }
  }
}

可以让它做什么

检查项目及其运行情况

• 显示此脚本的文件，并解释每个函数的作用。
• 本周哪些函数执行失败了？显示 sendDigest 的执行历史。
• 过去 7 天内，此脚本有多少用户、执行次数和失败次数？

编写和迭代代码

• 创建独立项目，或创建绑定到 Doc、Sheet、Slides 或 Form 的脚本。
• 在一个文件中添加辅助函数，不改动其他文件。
• 重构前，将当前代码快照保存为一个带说明的版本。

部署、运行和回滚

• 部署版本 4 并显示其入口点——Web 应用 URL 或 API 可执行配置。
• 运行 sendDigest 并显示结果；如果脚本抛出异常，则显示堆栈跟踪。
• 将部署重新指向版本 3，同时不更改其 URL。

项目如何变更

1. create_project 会创建一个项目——可以是独立项目，也可以绑定到 Doc、Sheet、Slides 或 Form。请保留返回的 scriptId：API 无法列出项目。
2. 代码以文件形式存放在 HEAD 中，文件按名称（不带扩展名）寻址。默认情况下，update_project_content 会合并内容——更新或新增你指定的文件，并保留其余文件——只有在明确要求时才会替换整个文件集；appsscript 清单永远无法删除。
3. create_version 会将 HEAD 快照保存为不可变版本——无法编辑或删除，版本号只会递增。
4. 部署会将某个版本作为 Web 应用或 API 可执行文件对外提供。更新部署会将其指向另一个版本，而不会更改其 URL；自动生成的 @HEAD 部署无法删除。

API 也无法删除项目——这意味着需要删除其 Drive 文件，而本服务不支持此操作。run_function 需要 API 可执行部署、与脚本属于同一 Cloud 项目的 OAuth 客户端，以及令牌中包含脚本自身所需的作用域；Apps Script 会在 6 分钟后停止任何执行。执行历史会显示状态和耗时，但不会显示错误消息——错误消息可在 Cloud Logging 中查看，也可以通过重新运行函数来获取。

可以进行哪些变更

AI 客户端控制确认提示。服务会标记读取、写入和具有破坏性的工具，让客户端能够区分检查操作与在线变更。

获取访问权限

Google Apps Script 需要 OAuth 2.0；仅有 API 密钥并不足够。有两种接入方式，第一种无需配置文件。

在聊天中连接（推荐）

说“连接 Google Apps Script”，助手就会带你完成整个流程：

1. setup_instructions 会打印检查清单：创建或选择 Google Cloud 项目、启用 Apps Script API、配置同意屏幕并创建 Desktop app OAuth 客户端。
2. 下载该客户端的 JSON（“Download JSON”），并将其路径提供给助手——set_client 会以仅所有者可访问的权限保存文件。密钥不会经过对话。
3. start_login 会返回 Google 授权链接。在这台机器上打开链接并批准；授权码会通过 PKCE 返回到监听一次请求的 127.0.0.1 服务，不会经过聊天。
4. finish_login 会交换授权码，并将令牌保存到 ~/.config/mcp-google-apps-script/credentials.json（权限模式为 0600）；随后通过实际调用 Apps Script API 验证令牌——因此如果 API 仍处于关闭状态，此时就会发现问题。

每次调用时都会重新读取令牌，因此连接会立即生效——无需重启 AI 应用。auth_status 会显示已连接的内容，logout 会撤销并删除连接。

环境变量（CI、无人值守安装）

1. 创建或选择一个 Google Cloud 项目，并启用 Google Apps Script API。

2. 在 script.google.com/home/usersettings 中开启每个账号的开关——否则每次调用都会失败并返回 403。

3. 配置 OAuth 同意屏幕，并创建 桌面应用 OAuth 客户端。

4. 授权拥有这些脚本的 Google 账号。启用 Use your own OAuth credentials 后，可通过 OAuth 2.0 Playground 获取刷新令牌。

5. 请求你计划使用的工具所需的范围：

   https://www.googleapis.com/auth/script.projects
   https://www.googleapis.com/auth/script.deployments
   https://www.googleapis.com/auth/script.processes
   https://www.googleapis.com/auth/script.metrics
   

   若只用于检查，请将前两个范围替换为只读版本 script.projects.readonly 和 script.deployments.readonly；list_processes 和 get_project_metrics 仍需要 script.processes 和 script.metrics，它们没有更窄的范围。run_function 不需要这些范围——相反，令牌必须包含目标脚本自身使用的所有范围，且 OAuth 客户端必须属于与该脚本相同的 Cloud 项目。

测试模式下的 OAuth 刷新令牌可能会在 7 天后过期。若需要长期访问，请发布 OAuth 应用，或在 Workspace 域中使用内部应用。请将客户端密钥和刷新令牌视为密码。

即使尚未配置凭据，setup_instructions 工具也会返回同一份检查清单并正常工作。

配置

所有变量均为可选项——即使一个都不设置，服务也会通过聊天连接。

* 请提供 OAuth 三项凭据或访问令牌。

数据、限制与后台工作

• 请求会发送到 Google Apps Script。 本地服务会刷新 Google OAuth 令牌并调用 Apps Script API。其匿名遥测包含安装 ID、软件包版本、AI 客户端和平台版本，以及工具名称——绝不包含 OAuth 令牌、脚本源代码、工具参数或提示词。设置 ASKADS_TELEMETRY=0 即可选择退出。
• 写入操作绝不会盲目重放。 遇到 429 时，服务会采用退避策略；读取操作在网络错误和 5xx 错误后也会重试，而写入操作在结果不确定的故障后不会重放——重复调用 create_version 会不断累积不可变版本，重复调用 run_function 则会将副作用执行两次。遇到结果不明确的故障后，请检查 list_versions 或执行历史记录，而不是重新发送请求。
• 没有后台轮询。 服务仅在被调用时运行，函数也仅在你要求时执行。脚本会在 Google 端保留自己的 Apps Script 触发器；如果你的 AI 应用支持计划任务，也可以定期检查执行历史记录。

技术文档

• MCP 能力目录 — 面向任务的页面，介绍每个工具。
• 所有工具和输入
• 开发文档
• 发布文档
• Google Apps Script API 参考

支持

发现了 Bug 或需要某个场景支持？创建 issue 或在 Telegram 中留言。

你已经读到最后了！