Google Sheets MCP

Google Sheets MCP

English | Русский

A1 Google Sheets MCP 让 AI 应用能够用自然语言操作 Google Sheets。查找电子表格、读取数据、写入和追加行、调整工作表和格式、创建图表并分享结果。

它使用 Google Sheets API 和你的 Google 账号。它将读取操作与写入操作分开，明确标记破坏性操作，并清晰说明 Sheets API 的限制，而不会让人误以为所有电子表格任务都能完成。

• 26 个工具。 搜索和创建电子表格、读取和写入范围、管理工作表、格式、数据验证、受保护范围、条件格式、结构化表格、图表和访问权限。
• 在对话中连接。 只需说“连接 Google Sheets”：服务会引导你配置 OAuth 客户端，使用 PKCE 在 127.0.0.1 上接收 Google 的重定向，并自行保存令牌——无需配置文件，也无需重启。
• 谨慎执行写入。 遇到结果不明的故障时，绝不会重放写入操作——重放追加操作可能会导致行重复；破坏性工具也会明确标记，方便你的 AI 客户端先征求确认。
• 仅支持 Sheets。 Drive 只是电子表格搜索和分享的内部依赖；不提供通用 Drive 工具，而且 raw_request 无法访问 Drive。
• 最小化 Google 权限范围。 spreadsheets 涵盖所有 Sheets 工具；只有搜索和分享电子表格时才需要 Drive 权限范围。

从只读问题开始：

找到季度预算电子表格，并总结其中每个工作表的内容。

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

一分钟了解它的工作方式

你： 展示销售报告电子表格的结构——其中的工作表、各自的大小和冻结行。

助手： 展示工作表、各自的大小、冻结的表头和其中的对象。不会进行任何更改。

你： 将“二月”工作表复制为“ 三月”工作表，并清除其中的数字，同时保留布局。

助手： 展示操作计划——复制工作表、重命名并清除数据范围——然后在进行任何更改前征求确认。

你： 确认。

助手： 复制工作表并清除数值。格式、数据验证和冻结行均会保留。

目录

• 快速开始
• 你可以让它做什么
• 电子表格如何更改
• 可以更改的内容
• 获取访问权限
• 配置
• 数据、限制和后台工作
• 技术文档
• 支持

快速开始

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

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

codex mcp add google-sheets \
  -- npx -y @a1-x-tech/mcp-google-sheets@latest

codex mcp list

claude mcp add \
  --transport stdio --scope user google-sheets \
  -- npx -y @a1-x-tech/mcp-google-sheets@latest

claude mcp list

{
  "mcpServers": {
    "google-sheets": {
      "command": "npx",
      "args": ["-y", "@a1-x-tech/mcp-google-sheets@latest"]
    }
  }
}

{
  "mcpServers": {
    "google-sheets": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@a1-x-tech/mcp-google-sheets@latest"]
    }
  }
}

{
  "servers": {
    "google-sheets": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@a1-x-tech/mcp-google-sheets@latest"]
    }
  }
}

你可以让它做什么

查找和读取数据

• 查找名称中包含“budget”的最新电子表格，并显示其结构。
• 读取 'Q3'!A1:F50 并汇总总计。
• 显示 Summary 工作表中的公式。

更新数字

• 将此表格写入 Sheet1!A1，包括公式。
• 将今天的数据追加为日志中的新行。
• 在一次批处理中更新多个区域，或清除草稿区域并保留其格式。

排版和呈现

• 添加一个“March”工作表，冻结标题行并将其设为粗体。
• 使用条件格式将负数标为红色并添加边框。
• 在单独的工作表中创建按月份统计收入的柱状图。
• 将数据转换为结构化表格，并添加带数据验证的下拉菜单。

保护和共享

• 保护总计行，使其只有我可以编辑。
• 授予一位同事编辑权限，并将其他所有人的权限设为只读。
• 显示当前有哪些人可以访问该文件。

电子表格如何变化

1. 值工具通过 A1 表示法（'Sheet name'!A1:C10）定位单元格；结构工具（工作表、格式、规则、表格、图表）通过从 0 开始的索引定位数字 sheetId。get_spreadsheet 会提供这些 ID——工作表标题不是地址。
2. 写入会覆盖其范围；append_values 会在最后一行数据之后添加行；null 单元格会被跳过，而不是清除。
3. clear_values 会清空值和公式，但保留格式、数据验证、备注和合并单元格。API 不支持撤销——删除工作表、行或列会销毁其中的数据。
4. 批量工具可在一次调用中处理多个范围或请求，且只计入一次配额；batchUpdate 是原子操作——其中的请求要么全部应用，要么全部不应用。

部分电子表格功能没有专用工具：合并单元格、命名范围、带状样式、筛选器、切片器、查找和替换，以及渐变条件格式规则，都需通过 raw_request 调用，且仅限 Sheets API 源站。新建的电子表格会放在“我的云端硬盘”根目录——目前不支持将其移入文件夹，manage_permissions 也无法转移所有权。

可以进行的更改

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

获取访问权限

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

从聊天中连接（推荐）

说“连接 Google Sheets”，助手就会引导你完成整个流程：

1. setup_instructions 会打印检查清单：创建或选择 Google Cloud 项目、启用 Google Sheets API、配置授权同意屏幕，并创建 桌面应用 OAuth 客户端。
2. 下载该客户端的 JSON 文件（“Download JSON”），并将其路径提供给助手——set_client 会以仅所有者可访问的方式保存。密钥不会经过对话传递。
3. start_login 会返回 Google 授权链接。在此设备上打开链接并批准；授权码会通过 PKCE 返回给 127.0.0.1 上的一次性监听器，不会经过聊天传递。
4. finish_login 会交换授权码，并将令牌保存到 ~/.config/mcp-google-sheets/credentials.json（模式 0600）。

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

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

1. 创建或选择一个 Google Cloud 项目，并启用 Google Sheets API。如果需要搜索和共享电子表格，也要启用 Google Drive API。

2. 配置 OAuth 同意屏幕，并创建 Desktop app OAuth 客户端。

3. 授权拥有电子表格或有权编辑电子表格的 Google 账号。启用 Use your own OAuth credentials 后，可以通过 OAuth 2.0 Playground 获取刷新令牌。

4. 请求最小权限范围：

   https://www.googleapis.com/auth/spreadsheets
   

   该权限范围涵盖所有 Sheets 工具。只有 search_spreadsheets 和 manage_permissions 还需要额外的 Drive 权限范围：https://www.googleapis.com/auth/drive，或者仅用于搜索的 drive.readonly，或用于通过此应用创建的文件的 drive.file。

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

配置

所有变量都是可选的——即使不设置任何变量，服务也会从聊天中连接。

* 请提供 OAuth 三项配置或访问令牌。没有凭据时，服务仍会启动并列出其工具；首次调用时会提示需要设置哪些变量。

数据、限制与后台工作

• 请求会发送至 Google。 本地服务会刷新 Google OAuth 令牌并调用 Sheets API；仅在搜索和共享电子表格时，还会调用 Drive API。匿名遥测包含安装 ID、软件包版本、AI 客户端和平台版本，以及工具名称——绝不会包含 OAuth 令牌、电子表格数据、工具参数或提示词。设置 ASKADS_TELEMETRY=0 可选择退出。
• Google 会实施每分钟配额限制。 文档所述的限制为每个项目每分钟 300 次读取和 300 次写入，每个用户每分钟各 60 次；无论批量调用包含多少个范围或请求，都只计为一次。一个电子表格最多包含 10,000,000 个单元格。遇到 429 时，服务会采用退避策略；读取操作也会在网络错误和 5xx 错误后重试，而写入操作在结果不确定的失败后不会重放。
• 没有后台轮询。 服务仅在被调用时运行。如果你的 AI 应用支持计划任务，就可以定期检查电子表格。

技术文档

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

支持

发现 Bug 或有使用场景需求？创建 Issue，或在 Telegram 上留言。

你已读到最后！