google-sheets-mcp

google-sheets-mcp

将 Google Sheets 用作 MCP 工具。读取和写入单元格区域，不会破坏底层公式。

这是一个通过标准输入/输出通信 MCP 的 Go 单一二进制文件。它作为客户端的子进程，在你自己的计算机上运行，并使用你自己的 Google 账号。无需托管服务端，无需共享部署，也无需服务账号：创建一个 Google OAuth 客户端，登录一次，刷新令牌就会保存在操作系统的密钥链中。

它在电子表格内部工作。查找、共享、移动和将文件移至回收站，以及文件修订历史，都属于基于 Drive API 构建的服务。这里支持单元格评论，也支持单元格备注。

为什么选择 google-sheets-mcp

电子表格的 API 调用没有撤销功能，而且你看到的值很少能代表单元格的全部内容：底层可能还有公式、不同的存储类型或备注。因此，这里的写入操作会受到保护，而不是盲目信任。write_values 会先读取目标区域；如果其中有非空内容但未设置 overwrite，或者有公式但未同时设置 overwrite_formulas，就会拒绝覆盖，并逐次指出具体单元格。每次覆盖都会附带被替换内容的检查点；Google 在导入过程中对任何值所做的更改也会反馈给你。

它还会处理索引计算。范围始终采用 A1 表示法，工作表标题会自动加引号——Google 会使用账号语言命名第一个工作表，因此名称通常不是英文——而 A1 转换为 GridRange 的唯一位置集中在一个程序包中。

它在电子表格内部工作。查找、共享、移动和将文件移至回收站，以及文件修订历史，都属于基于 Drive API 构建的服务。这里支持单元格评论，也支持单元格备注。

读取、写入、格式设置、与区域关联的对象、gsheets:// 资源、持久锚点、图表、数据透视表、Connected Sheets 数据源和单元格评论均可使用。 这二十五个工具及其 参数和返回字段都保持稳定：破坏性更改必须提升主版本号，并且有一道检查会将每次提交与最新版本记录的接口进行比较。它由一个 MCP 客户端驱动；在将它用于第二个客户端之前，了解这一点很重要。历史记录见 docs/architecture.md 的 §16。

安装

go install github.com/mmedum/google-sheets-mcp/v4/cmd/google-sheets-mcp@latest

也可以从最新版本下载归档文件——支持 Linux、macOS 和 Windows，以及 amd64 和 arm64——并在运行前验证：

sha256sum -c checksums.txt --ignore-missing

# The checksum file is signed with a keyless Sigstore certificate tied to
# the release workflow's identity. The bundle carries both.
cosign verify-blob checksums.txt \
  --bundle checksums.txt.bundle \
  --certificate-identity-regexp 'https://github\.com/mmedum/google-sheets-mcp/' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

# And the archive itself carries build provenance.
gh attestation verify google-sheets-mcp_*.tar.gz --repo mmedum/google-sheets-mcp

每个归档文件还附带 SBOM，让你了解未自行构建的二进制文件包含哪些内容。构建具有可复现性：使用 -trimpath，并采用提交的时间戳而非构建时间戳，因此重新构建某个标签会得到相同的字节内容。

Claude Desktop

每个版本还会附带一个 .mcpb 捆绑包。打开后，Claude Desktop 会安装该服务，并询问客户端配置中需要填写的设置：OAuth 客户端 JSON、配置文件、只读模式、破坏性操作开关、Connected Sheets，以及可访问外部内容的公式——无需编辑配置文件。删除操作（enable_destructive）、Connected Sheets（enable_data_sources）以及获取 URL 或其他电子表格内容的公式（allow_external_formulas）默认均处于关闭状态，除非你主动开启；只读模式会让这三项都无法注册或启用。

此服务不会在调用前征求任何人的同意。Claude Desktop 会逐个批准工具，可选择“允许一次”或“始终允许”；将工具设为始终允许后，之后调用便无需再次询问，因此除非需要使用相关工具，否则请保持开关关闭。

该捆绑包支持 macOS、Windows 和 Linux，且每个平台都支持两种架构：macOS 使用通用二进制文件，Windows 使用 amd64，Linux 则使用一个小型启动器，在启动时选择对应的二进制文件，因为捆绑包清单没有用于指定架构的字段。其 SHA-256 值位于同一份经过签名的 checksums.txt 中。

该捆绑包不会为你登录。请同时安装二进制文件，并运行一次 google-sheets-mcp login -secret <your client JSON>；捆绑包会使用同一份凭据。OAuth 客户端字段留空时，将使用登录时记录的客户端；在该字段中选择的文件必须是同一个客户端，因为刷新令牌与之绑定。Connected Sheets 还需要通过以下命令登录，以请求相应权限范围：google-sheets-mcp login -enable-data-sources=true -secret <your client JSON>。Claude Code 不会安装 .mcpb 文件，因此请使用下面的命令。

设置 Google

你需要自己的 OAuth 客户端。首次设置大约需要 15 分钟，docs/gcp-setup.md 会说明具体步骤和原因。简而言之，按 doctor 检查项目的顺序：

1. 创建 Google Cloud 项目。

2. 启用 Google Sheets API 和 Google Drive API——启用后者是为了使用 search_spreadsheets，这是此服务调用的唯一 Drive API。

3. 配置同意屏幕：Workspace 账号选择 Internal，个人账号选择 External + Testing——这意味着每周都要重新运行 login，因为 Google 会让测试应用的刷新令牌过期。

4. 添加以下两个作用域，login 请求的正是这两个：

   作用域	用途
   https://www.googleapis.com/auth/spreadsheets	此服务在电子表格中执行的所有操作
   https://www.googleapis.com/auth/drive.readonly	search_spreadsheets，仅此而已

   仅当你想使用 Connected Sheets 时，才需要添加第三个作用域：

   作用域	用途
   https://www.googleapis.com/auth/bigquery.readonly	connect_data_source 和 manage_data_source，且仅在 GSHEETS_ENABLE_DATA_SOURCES=true 时使用

   只有启用该设置后，login 才会请求此作用域，因此不启用时，同意屏幕上就只有上面的两个作用域。Google 不会在缺少此作用域时执行 addDataSource——并会提示“Please include bigquery.readonly scope”，所以不会出现令人意外的半可用状态。

   特意使用 drive.readonly，而不是 drive 或 drive.file：此服务只会查找电子表格，不会创建、移动或删除文件；较窄的作用域能确保这一点，而不只是一个承诺。这也是实时驱动程序无法自行清理的原因。

   设置 GSHEETS_READ_ONLY=true 后，login 会请求 https://www.googleapis.com/auth/spreadsheets.readonly，而不是第一个作用域，并且不会注册写入工具。

5. 创建一个类型为 Desktop app 的 OAuth 2.0 Client ID，然后下载 JSON 文件。

然后登录：

google-sheets-mcp login -secret ./client_secret.json

login 会打印授权 URL，然后尝试打开浏览器；如果无法打开，URL 也已显示在屏幕上。回调会使用 PKCE 和 state，全程发送到随机端口上的 127.0.0.1。刷新令牌会存入操作系统密钥环；如果没有密钥环，则会存入配置目录下权限为 0600 的文件，命令也会告知你这一点。

google-sheets-mcp status 会显示已登录的账号以及令牌的存储位置。google-sheets-mcp logout 会在 Google 端撤销令牌并删除本地副本。google-sheets-mcp doctor 会检查凭据、已授予的作用域以及 Google 的实际响应，并指出缺少的内容——它会隐藏客户端 ID 和账号，因此可以安全地将输出粘贴到问题报告中。

google-sheets-mcp status --json 会在 stdout 上将相同状态打印为一个 JSON 对象，供需要在启动此服务前确认其是否已配置的脚本使用。credentials.configured 是用于分支判断的字段；只有在移除字段或字段含义发生变化时，schema_version 才会变更；账号会像文本输出一样，仅显示其域名。人类可读输出中的标签可以在任何版本中重新措辞；对象则不会。

通过 SSH 登录

回调会发送到远程主机的回环地址，而你的浏览器在本地运行，因此需要转发端口。端口是随机选择的，并且只有在登录已等待时才会打印，所以请从打印出的 URL 中读取端口——它会以百分号编码的形式显示为 127.0.0.1%3A<port>——然后在第二个本地终端中运行：

ssh -N -L <port>:127.0.0.1:<port> user@remote-host

然后在本地打开该 URL。

连接客户端

Claude Code：

claude mcp add google-sheets -- google-sheets-mcp

或者，在客户端配置文件中：

{
  "mcpServers": {
    "google-sheets": {
      "command": "google-sheets-mcp"
    }
  }
}

Claude Desktop 会从自己的配置文件中读取相同格式的配置。如果二进制文件不在应用的 PATH 中，请在配置中使用其绝对路径。

每个设置都是一个 GSHEETS_* 环境变量，并有一个同名标志，详见 docs/configuration.md。 现在值得了解的三个设置：GSHEETS_READ_ONLY=true 会请求只读权限范围，并且只注册读取工具； GSHEETS_ENABLE_DESTRUCTIVE=true 会注册五个用于删除内容的工具；GSHEETS_PROFILE 可让一台机器同时保存工作账户和个人账户。

工具

共有 25 个工具。除 search_spreadsheets 外，其他工具只需要 Sheets 权限范围；在只读模式下，读取工具会改为请求 spreadsheets.readonly。

工具	功能	权限范围
get_spreadsheet	电子表格概览：标题、链接、区域设置，以及每个工作表的准确标题、ID、大小、冻结行数、隐藏状态和内容；还包括命名范围、表格、受保护范围和筛选视图。不读取单元格数据，因此读取 10 个单元格和 1000 万个单元格的电子表格，成本相同。请先调用此工具	spreadsheets
read_range	读取指定范围的网格：顶部为列字母，侧边为行号。show=both 会在每个值下方显示生成该值的公式。按单元格数和字符数设有预算，支持继续读取，并且每次读取都会返回一个检查点	spreadsheets
read_formatting	查看范围的外观——数字格式、字体、颜色、边框和对齐方式——按格式相同的单元格块展示，而非逐个单元格展示；还会显示决定单元格外观但不直接附加在单元格上的合并、条件规则、交替颜色、验证规则和备注	spreadsheets
search_spreadsheets	按标题中的部分文字、表格内的文本、所有者或修改时间查找电子表格。这是此服务发出的唯一 Drive 调用	drive.readonly
find_in_spreadsheet	在一个电子表格中搜索文本或 RE2 模式，并返回 A1 地址，同时指出每个匹配项位于值、值下方的公式，还是旁边的备注中	spreadsheets
create_spreadsheet	创建一个新电子表格，可选择添加额外工作表和初始值。返回其概览，其中包括后续每次调用都需要的 ID	spreadsheets
write_values	写入一个矩形区域：先拒绝任何会覆盖你无法看到的内容的写入，然后报告 Google 实际存储的、与发送内容不同的每个值。覆盖写入会附带被替换内容的检查点	spreadsheets
append_rows	在数据块之后添加行，并报告实际写入的位置——目标位置由 Google 决定，同一工作表使用不同范围时，追加位置也会不同。此操作会插入行，因此绝不会覆盖现有行	spreadsheets
format_cells	通过一个原子批次应用数字格式、字体、颜色、边框、对齐方式、换行、合并和备注。合并、清除和添加备注这三种操作会移除内容，每种操作在获得确认前都会被拒绝	spreadsheets
manage_range	添加、更新或删除附加到范围的内容：命名范围、受保护范围、验证规则、表格及其列类型、交替颜色，或条件格式规则或色阶。现有项目通过其覆盖范围命名，而非通过 ID 命名	spreadsheets
transform_range	对范围进行排序、替换、修剪、去重、拆分、随机打乱、填充、复制或移动——这些操作会移动数据，但无需指定新地址，因此每次操作都会先读取目标位置上的内容	spreadsheets
manage_anchor	为行、列或工作表添加标签，以便在电子表格经过编辑后再次找到它。锚点会随其所在行一起移动，适用于插入、删除、移动和排序；而 A1 地址在有人插入行时就会失效。在任何需要指定范围或带状区域的地方，都可以传入 anchor:<name>，但 delete_dimensions 和 clear_values 除外；这两个工具直接接收行或范围本身，因此调用内容会明确显示将要删除的内容	spreadsheets
manage_chart	添加、更新、移动、删除或列出图表和切片器。图表浮于网格之上，因此添加图表不会覆盖任何内容；其数据使用 A1 格式指定，每个系列对应一个范围。列表会报告哪些图表丢失了系列——例如删除图表所用的列时会发生这种情况，而 Sheets 不会提供任何提示	spreadsheets
manage_pivot_table	添加、更新、删除或列出数据透视表，支持按日期或数字范围分组、筛选和计算值。列必须通过 A1 格式或标题指定，不能通过计数指定；每个结果都会报告数据透视表当前覆盖的矩形区域：其大小根据数据计算，而非手动选择。列表会按此工具接受的格式读取并返回每条规则	spreadsheets
connect_data_source	默认关闭：通过 Connected Sheets 连接 BigQuery 查询或表格。Google 会为其创建一个工作表并运行查询，费用由你指定的 Cloud 项目承担，包括现在及每次刷新时产生的费用	spreadsheets、bigquery.readonly
manage_data_source	默认关闭：刷新一个 Connected Sheets 数据源、取消刷新，或列出已连接的数据源。get_spreadsheet 已能说明电子表格是否包含数据源，无需额外权限范围	spreadsheets、bigquery.readonly
read_cell_comments	查看电子表格单元格上的评论线程：每条评论当前所在的单元格、打开或已解决的状态、指派对象，以及所有帖子。线程会随所在单元格一起移动；即使所在行已删除，线程仍会列出，但不再显示单元格	spreadsheets
manage_cell_comment	对单元格发表评论、回复、编辑帖子、解决或重新打开评论。Google 会向被指派对象发送电子邮件，也可能通知文本中提到的地址；这是此服务联系电子表格以外人员的方式	spreadsheets
manage_sheet	添加、重命名、复制工作表，复制到另一个电子表格，隐藏、取消隐藏、重新排序、调整大小、冻结或设置颜色	spreadsheets
edit_dimensions	插入、移动、调整大小、自动调整大小、分组、取消分组、隐藏或取消隐藏行和列	spreadsheets
delete_dimensions	破坏性操作，默认关闭：删除行或列及其中的数据，并先统计将删除的内容	spreadsheets
clear_values	破坏性操作，默认关闭：清除范围中的值，同时保留格式、备注和验证规则	spreadsheets
delete_sheet	破坏性操作，默认关闭：删除工作表及其中的所有内容，并先统计将删除的内容	spreadsheets
delete_cell_comment	破坏性操作，默认关闭：删除评论线程及其回复，或删除一条回复。解决评论会保留评论，通常这才是需要的操作	spreadsheets
delete_data_source	破坏性操作，默认关闭：删除一个 Connected Sheets 数据源、Google 为其创建的工作表及该工作表中的所有内容；Google 会取消源数据上已有内容与该数据源的关联。调用时需指定该工作表的标题。无需 BigQuery 权限范围，因此可以访问由其他人连接的数据源	spreadsheets
除非设置 GSHEETS_ENABLE_DESTRUCTIVE=true，否则这五个破坏性工具根本不会注册；调用时仍需传入 confirm: true。

除非设置 GSHEETS_ENABLE_DATA_SOURCES=true，否则 connect_data_source 和 manage_data_source 也不会注册——而且此设置还会让 login 请求第三个作用域。默认关闭此设置，是因为 Connected Sheets 要运行，必须先有一个启用了 BigQuery 并关联了账单的 Cloud 项目；对于大多数人而言，一个在授权页面请求 BigQuery 权限的电子表格服务，等于要求他们授权使用自己并没有的产品。

审批调用

每次调用都由 MCP 客户端审批；服务本身不会向你询问。claude.ai 和 Codex 会提示审批标记为破坏性的工具：五个删除工具，以及六个可能移除其所作用内容的写入工具（write_values、transform_range、format_cells、manage_range、manage_chart 和 manage_pivot_table）。VS Code 会提示审批所有写入工具。在 Claude Code 中，无论你的规则如何，delete_data_source 每次调用都会询问，因为它会接受一个工作表并取消所有基于该数据源构建的内容的关联，而 Sheets 无法撤销此操作。对于其他工具，请在设置中的 permissions.ask 下逐一列出要审批的调用，并将服务器名称替换为你为其指定的名称（而不是 google-sheets）。例如，以下写入操作会执行删除、启动计费查询，或可能向他人发送电子邮件：

{
  "permissions": {
    "ask": [
      "mcp__google-sheets__delete_sheet", "mcp__google-sheets__delete_dimensions",
      "mcp__google-sheets__clear_values", "mcp__google-sheets__delete_cell_comment",
      "mcp__google-sheets__delete_data_source", "mcp__google-sheets__connect_data_source",
      "mcp__google-sheets__manage_cell_comment"
    ]
  }
}

如果你按照 3.1.0 的建议将删除操作加入了允许列表，请将它们移到 ask：服务自身的询问已不存在，因此允许的删除操作现在会在无人询问的情况下执行。无人监看时运行的客户端可以执行其设置中登记的所有写入操作，因此暂时关闭 GSHEETS_ENABLE_DESTRUCTIVE 和 GSHEETS_ENABLE_DATA_SOURCES。

资源

有两个，供附加电子表格而非调用工具的客户端使用。这里没有静态列表——枚举某人的电子表格属于 Drive 列表操作，应由基于 Drive API 构建的服务负责；也没有订阅，因为 Sheets API 不支持推送，也没有变更动态。

URI	内容
gsheets://{spreadsheet}	概览卡：每个工作表的准确标题、ID 和大小，以及命名范围、表格和受保护范围。不读取单元格
gsheets://{spreadsheet}/{sheet}	该工作表的已用范围，以 CSV 格式呈现——即包含内容的行和列，而非工作表分配的大小。工作表标题经过百分号编码

安全

写入操作绝不会破坏其无法看到的内容。 Sheets API 不支持撤销，因此在构建请求前拒绝执行是唯一的防护措施。覆盖任何非空内容都需要 overwrite；覆盖公式还需要 overwrite_formulas，因为公式及其结果在读取时看起来完全相同。每次拒绝都会指出涉及的单元格，以及允许执行此操作所需的参数。覆盖操作还需要 expect_checkpoint，即将被替换单元格的检查点；拒绝信息和试运行都会提供此检查点：读取之后协作者所做的编辑会使写入变成 [conflict]，而不是在未察觉的情况下被替换。

同样的防护措施也适用于第 2 阶段新增的所有功能。以下每一项都经过确认是会造成无声数据丢失，而不是仅凭推测认定会如此：

• 合并会保留每个合并区域左上角的值，并丢弃其余值，但响应中不会说明这一点；
• **clear_format**会移除 Sheets 无法恢复的格式；
• 设置或清除备注会替换掉一些仅靠读取值无法看到的内容；
• 粘贴或自动填充会作用于你未指定的单元格，因此会像其他目标一样读取并保护目标矩形区域；
• **text_to_columns**会向右侧的列溢出；
• 带有 **in_formulas 的 find_replace**会改写单元格的计算结果，而不是显示内容；
• 删除表格会连同其范围内的所有条件格式规则一起删除——这是通过实时 API 验证的，而非在任何地方读取到的；
• 删除行或列会一并删除其上的任何锚点，而 Google 的回复也不会提到这一点。delete_dimensions 会在删除前列出这些锚点。

超出保护范围的情况：

• 公式若会访问外部内容，由操作者自行决定。 IMPORTXML、 IMPORTDATA、IMPORTHTML、IMPORTFEED、IMAGE 和 HYPERLINK 会让 Google 获取 URL，而 IMPORTRANGE 会导入另一个电子表格的内容。 除非启动服务时设置了 GSHEETS_ALLOW_EXTERNAL_FORMULAS=true，否则所有写入都会拒绝这些公式；没有任何参数可以解除此限制。

• 受限的删除操作会明确列出删除对象。 delete_dimensions 会列出要删除的行或列，而 clear_values 会列出 A1 格式的范围：不会列出锚点，也绝不会遗漏，因此客户端显示的调用会明确说明将删除什么。

• 会报告数据强制转换，绝不隐瞒。 input: typed 会按用户输入的方式解析，因此 007 会变成 7，而 2026-09-05 会变成日期。 每次写入都会读取 Google 存储的内容，并指出每个被更改的值；对于日期，还会显示单元格仍然显示的内容，避免将序列号误认为数据丢失。input: literal 会原样存储你发送的内容，服务不会将两者互相替换。

• 每个写入操作都支持 dry_run。 Sheets 没有建议模式，因此预览会报告保护机制发现的内容以及将要发生的更改，且不会发送任何内容。该功能通过反射发现，而非按工具逐一声明，因此支持此标志的写入操作一定会遵守它。

• 只读模式不会注册写入工具。 未注册的工具无法调用，无论客户端处于何种权限模式。此模式在启动服务时设置，因此绑定的是整个会话，而非单次调用。

• 每次读取都会显示地址，因此模型无需计数，就能写回刚刚读取的内容。A1 是约定：模型看不到 GridRange，基于零的半开区间运算集中在一个带表格测试的包中。

• 读取工作表名称，不会凭空假定。 Google 会根据账号语言为第一个工作表命名，因此葡萄牙语账号中并不存在 Sheet1。任何工具都不会默认指定工作表，描述中也不会将其作为示例；如果工作表不存在，操作会被拒绝，并返回实际存在的工作表标题。

• 调用前会控制读取量。 系统会根据工作表的实际范围解析窗口，并发送有限范围，因此开放式的 A:Z 不会变成内存中的整列。

• 日志绝不包含数据内容。 日志只记录方法、工具、结果、耗时和截断后的电子表格 ID。单元格值、公式、标题、范围和搜索词都不会写入日志——搜索词会通过请求 URL 进入日志，因此传输错误会剔除搜索词；如果这些内容中的任何一项出现在日志中，测试就会导致构建失败。

工作原理

MCP client ──stdio──► google-sheets-mcp
                       ├── tools     one handler per tool; one Kind decides its annotations
                       ├── service   the rules: resolve, budget, guard, report
                       ├── plan      typed batchUpdate requests, and the write guards
                       ├── grid      the server's view of a rectangle, and its checkpoints
                       ├── render    every word a caller reads
                       ├── a1        A1 notation ↔ GridRange, the only place that conversion lives
                       ├── gapi      REST client for Sheets and the one Drive call
                       └── auth      refresh token → access token

获取帮助

如果某项功能无法正常工作，请运行 google-sheets-mcp doctor。它会检查凭据、已授予的权限范围，以及 Google 实际返回的内容，并指出缺少什么——首次运行时遇到的大多数问题，都是因为未启用某个 API，或是授权同意屏幕中没有添加你的账号。

如果这样仍无法解释问题， 请提交问题。 切勿在问题中粘贴电子表格 ID 或 URL、单元格内容、 client_secret.json 或令牌；请改为描述其结构。安全问题请私下通过 SECURITY.md 报告。

版本管理

在同一个主版本中，工具名称及其输出字段保持稳定。任何需要你采取行动的更改——例如新增权限范围、再次登录，或更改客户端配置中的命令——都会在 CHANGELOG.md 中标记为 Breaking:；该文件也是发布说明的来源。

开发

make build     # the binary
make test      # race detector, coverage floor
make check     # everything CI runs

make check 是完成标准：格式检查、包括构建标签代码在内的 go vet、golangci-lint、带有逐包覆盖率下限的竞态测试、govulncheck、许可证允许列表、两项机密信息和标识符扫描、stdio 冒烟测试、与已发布工具接口的架构差异检查、检查 Claude Desktop 程序包清单是否只列出将被打包的文件、检查 Makefile 和 CI 是否运行相同的任务，以及一项陈旧度检查，用于在 README、文档或变更日志与代码不一致时使检查失败。

检查全部通过并不代表一切都完成了。任何涉及写入路径或 API 响应结构的更改，都还需要使用真实账号运行测试，并阅读测试记录，而不是只统计结果——命令见 docs/development.md。

文档

• docs/architecture.md — 请求流程、程序包布局、阶段计划、贡献者不应撤销的决策，以及记录了哪些内容经过 API 验证、API 实际行为又与预期有何不同的证据日志。
• docs/configuration.md — 所有设置。
• docs/development.md — 构建、测试以及使用真实账号运行测试。
• docs/security.md — 威胁模型。
• docs/runbook.md — 轮换或恢复凭据。

贡献

问题和缺陷请提交到问题跟踪；欢迎提交拉取请求。CONTRIBUTING.md 介绍了分支和评审流程，且必须通过 make check。

安全

SECURITY.md 说明了如何报告漏洞。

行为准则

CODE_OF_CONDUCT.md — Contributor Covenant 3.0。

许可证

Apache 2.0 — 详见 LICENSE。