gsheets-mcp

一个本地 MCP（Model Context Protocol）服务器，让 Claude 通过 Google Sheets API v4 读写你的 Google Sheets。

它完全运行在你自己的机器上。你使用自己的 Google 账号通过 OAuth2（"已安装应用"/桌面流程）进行身份验证，你的数据永远不会经过任何第三方服务器。

基于 MIT 许可证免费开源。 无遥测，无第三方服务器。

🌐 网站： https://gsheets-mcp.trombella.org/

你能获得什么

大多数工具接受电子表格 ID——即表格 URL 中的长字符串： https://docs.google.com/spreadsheets/d/<这就是ID>/edit。 你也可以用 list_spreadsheets 来发现 ID，而不必手动复制。

Related MCP server: sheetsdb-mcp-server

前置要求

• Node.js 18+（node --version）。

• 一个 Google 账号。

第 1 部分 — 设置 Google Cloud（一次性）

你需要一个 OAuth"桌面应用"客户端，以便服务器可以请求你授权访问你的表格。

1. 创建 Google Cloud 项目

1. 前往 https://console.cloud.google.com/。

2. 顶栏 → 项目下拉菜单 → 新建项目。给它起个名字（例如 gsheets-mcp）并创建。确保它已被选中。

2. 启用 API

1. 前往 API 和服务 → 库（https://console.cloud.google.com/apis/library）。

2. 搜索 Google Sheets API，打开它，点击启用。

3. 搜索 Google Drive API，打开它，点击启用。

Drive API 仅被 list_spreadsheets 用于枚举你的表格，通过只读的 drive.readonly 范围。它不用于修改、移动或删除文件。

3. 配置 OAuth 同意屏幕

1. 前往 API 和服务 → OAuth 同意屏幕。

2. 用户类型：外部 → 创建。（内部仅适用于 Google Workspace 组织。）

3. 填写必填字段：应用名称（例如 gsheets-mcp）、你的邮箱作为用户支持邮箱和开发者联系信息。其余可以留空。保存并继续。

4. 范围：你可以跳过在此处添加范围（应用会在登录时请求它们）。保存并继续。

5. 测试用户：点击添加用户并添加你自己的 Google 邮箱。这是必需的——在"测试"模式下，只有列出的测试用户才能授权该应用。保存并继续。

6. 将应用保持在测试模式。这对个人使用来说没问题，并且对你的测试用户账号永不过期。（发布到"生产"会触发 Google 的应用验证，你在这里不需要。）

4. 创建 OAuth 客户端凭据

1. 前往 API 和服务 → 凭据。

2. 创建凭据 → OAuth 客户端 ID。

3. 应用类型：桌面应用。给它命名（例如 gsheets-mcp desktop）。创建。

4. 在确认对话框中，点击下载 JSON。此文件包含你的 client_id 和 client_secret。

5. 放置凭据文件

将下载的文件保存为配置目录中的 credentials.json：

mkdir -p ~/.config/gsheets-mcp
mv ~/Downloads/client_secret_*.json ~/.config/gsheets-mcp/credentials.json

请将此文件保密——它已被 git 忽略。你可以使用 GSHEETS_MCP_CREDENTIALS 环境变量覆盖其位置（参见 .env.example）。

第 2 部分 — 安装和构建

在项目文件夹中：

npm install
npm run build

第 3 部分 — 登录（一次性）

运行交互式登录。它会在浏览器中打开 Google 的同意屏幕；批准访问后，令牌将保存到 ~/.config/gsheets-mcp/token.json（此后自动刷新）。

npm run login
# equivalently: node dist/index.js login

由于应用处于测试模式，Google 会显示 "Google 尚未验证此应用" 警告。这对你自己的应用来说是正常的—— 点击**高级 → 前往 gsheets-mcp（不安全）**并继续。然后授予两个请求的权限（见下文）。

当你在终端中看到 ✅ 授权完成 时，就完成了。

请求的范围：

• https://www.googleapis.com/auth/spreadsheets — 读写你的电子表格。

• https://www.googleapis.com/auth/drive.readonly — 只读，仅被 list_spreadsheets 用于枚举你的表格。它不能修改或删除文件。

要随时撤销访问权限，请访问 https://myaccount.google.com/permissions。

注意： 如果你升级了服务器且请求的范围发生变化，你必须重新运行 npm run login——先前授予的同意不涵盖新的范围。每台机器也是如此（每台计算机存储自己的令牌）。

第 4 部分 — 将服务器添加到 Claude Desktop

打开 Claude Desktop 的配置文件：

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

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

在 mcpServers 下添加一个 gsheets 条目，指向编译后的入口点。使用本项目中 dist/index.js 的绝对路径：

{
  "mcpServers": {
    "gsheets": {
      "command": "node",
      "args": ["/absolute/path/to/google-sheets-mcp/dist/index.js"]
    }
  }
}

保存文件并完全退出并重新打开 Claude Desktop。你现在应该能看到 gsheets 工具可用。尝试向 Claude 提问，例如：

"列出我的 Google Sheets，然后读取名为 'Budget' 的表格中的 A1:C5。"

在 Claude Code 中使用

claude mcp add gsheets -- node /absolute/path/to/google-sheets-mcp/dist/index.js

使用示例（向 Claude 提问的内容）

• 列出： "列出我的 Google Sheets" / "查找名称包含 'budget' 的电子表格。"

• 信息： "电子表格 <ID> 有哪些标签页？"（返回要使用的确切标签页名称）。

• 读取： "从电子表格 <ID> 中读取范围 Foglio1!A1:D10。"

• 更新： "将值 [[\"Name\",\"Score\"],[\"Ada\",42]] 从 Foglio1!A1 开始写入电子表格 <ID>。"

• 追加： "将行 [\"Grace\", 99] 追加到电子表格 <ID> 的 Foglio1。"

⚠️ 注意：标签页名称是本地化的

范围使用标签页（工作表）名称，例如 Sheet1!A1:D10。但默认标签页名称取决于你的 Google 账号语言：英文是 Sheet1，意大利文是 Foglio1，西班牙文是 Hoja1，法文是 Feuille1，依此类推。使用错误的名称会返回 Unable to parse range: …。

如果你不确定实际的标签页名称，请打开表格并读取底部的标签页标签，或者直接让 Claude 通过仅传递标签页名称作为范围（例如 Foglio1）来读取整个表格。一个专门列出确切标签页名称的 get_sheet_info 工具已在路线图上。

配置参考

全部可选；默认值开箱即用。参见 .env.example。

对于无头 / HTTP 模式（见下文），你可以通过环境变量提供凭据：

远程 / 移动使用（高级）

默认传输是 stdio（本地）。服务器也可以作为远程 MCP 连接器通过 HTTP 运行，这样你可以从无法启动本地进程的客户端访问它——例如 Claude 移动应用：

MCP_AUTH_TOKEN=$(openssl rand -hex 32) npm run serve:http   # listens on :8000/mcp

每个请求都必须发送 Authorization: Bearer <MCP_AUTH_TOKEN>。由于此端点可以写入你的电子表格，除了 Bearer 令牌之外，始终将其放在网络网关（Cloudflare Access、VPN）后面——切勿在互联网上裸奔。

一个现成的 Home Assistant OS 插件用于个人常开设置（位于 Cloudflare Tunnel 后面），位于 ha-addon/gsheets-mcp/——参见其 DOCS.md 获取完整的分步指南。

故障排除

• "未认证。请先运行一次性登录" — 你尚未登录，或者令牌文件缺失。运行 npm run login。

• "未找到 OAuth 客户端凭据" — credentials.json 不在服务器期望的位置。检查第 1 部分第 5 步。

• 浏览器中出现 403 access_denied — 你的 Google 账号未被列为测试用户。在 OAuth 同意屏幕 → 测试用户中添加它（第 1 部分第 3.5 步）。

• "请求的认证范围不足" — 你保存的令牌早于范围变更（例如 list_spreadsheets 需要 drive.readonly）。重新运行 npm run login 以重新同意。

• Unable to parse range: … — 标签页名称错误。标签页名称是本地化的（意大利文为 Foglio1，英文为 Sheet1）。使用 get_sheet_info 查看确切名称。

• 无 refresh_token 警告 — 在 https://myaccount.google.com/permissions 撤销应用，然后重新运行 npm run login。

• 工具未出现在 Claude Desktop 中 — 确认 claude_desktop_config.json 中的路径是绝对的并指向 dist/index.js，你已运行 npm run build，并且你已完全重启 Claude Desktop。

开发

npm run build       # compile to dist/
npm run watch       # recompile on change
npm run typecheck   # type-check without emitting

源码结构：src/index.ts（入口点）、src/auth.ts（OAuth）、src/sheetsClient.ts 和 src/driveClient.ts（API 封装）、src/tools/*（每个 MCP 工具一个文件）。

许可证

根据 MIT 许可证 发布。你可以自由使用、修改和分发。如果它为你节省了时间，你可以请我喝杯咖啡来支持开发——参见网站上的链接。☕

与 Google 无关联，也未获得 Google 认可。"Google Sheets" 是 Google LLC 的商标。