Google Sheets MCP Server

Google Sheets MCP Server

一个 MCP 服务，让 Claude、Cursor 或任何其他 MCP 客户端读取和写入你的 Google Sheets：列出电子表格中的工作表标签页、读取单元格范围、追加或更新行，以及将 Apify 数据集导出到工作表标签页。

它使用你自己的 Google 服务账号登录，因此没有共享配额、无需批准 OAuth 应用，也不会过期。此服务账号只能打开你与其共享的工作表。

有两种使用方式：

• 托管在 Apify 上（无需安装）：apify.com/oldjard/google-sheets-mcp。 当你的 Agent 调用服务时，Apify 会启动它；服务空闲后，Apify 会将其停止。费用按使用量收取，从你自己的 Apify 账号扣费（价格见下文）。
• 自行托管（免费）：克隆此仓库并自行运行。代码相同。

工具

工具	功能
list_sheets	列出电子表格中的工作表标签页，并显示其大小和链接
read_range	读取单元格（Leads!A1:D50、A1:D50 或整个工作表标签页）。较长的工作表标签页会分页返回，并提供下一个待读取的范围
append_rows	在最后一行下方添加行。对象会按名称与表头匹配（新字段会成为新列）。数组会按原样写入。可跳过工作表标签页中已有的行
update_range	从左上角单元格开始覆盖单元格，并在需要时扩展工作表标签页
export_dataset	将 Apify 数据集写入工作表标签页：追加、替换或仅写入新行

写入的值都是纯值，绝不会作为公式写入。每次调用最多读取或写入 5,000 行。如果工具无法执行某项操作（工作表未共享、工作表标签页名称错误、缺少密钥），它会返回通俗易懂的解决方法，例如需要共享工作表的准确邮箱地址。

Google 设置（约 5 分钟，只需设置一次）

你需要一个 Google 服务账号：这是一个机器人 Google 用户，只能访问你与其共享的工作表。 它是免费的，使用 Sheets API 时 Google 不会要求提供账单信息。

1. 打开 console.cloud.google.com，创建一个项目并选中它。
2. 打开 Google Sheets API 页面，然后点击 启用。
3. IAM 与管理 > 服务账号 > 创建服务账号。为其命名，跳过可选的角色步骤，然后点击完成。
4. 打开该服务账号，选择密钥 > 添加密钥 > 创建新密钥 > JSON。系统会下载一个 .json 文件。
5. 复制其 client_email。将你希望 Agent 使用的每个 Google Sheet 分享给该邮箱，并授予编辑者权限。
6. 将密钥转换为一行 base64：base64 -w0 key.json（在 macOS 上：base64 -i key.json）。

某些 Google Workspace 组织会禁止使用服务账号密钥。如果第 4 步提示因政策而无法创建密钥，请为该项目使用个人 Google 账号；只要与该邮箱共享，工作表可以存放在任何位置。

连接：托管在 Apify 上

使用 URL https://oldjard--google-sheets-mcp.apify.actor/mcp，并设置两个标头。对于 Claude Code：

claude mcp add --transport http google-sheets https://oldjard--google-sheets-mcp.apify.actor/mcp \
  --header "Authorization: Bearer <your Apify API token>" \
  --header "X-Google-Service-Account-Key: <the base64 line>"

其他客户端在 JSON 配置中使用相同的 URL 和 headers。

**定价（托管）：**每次成功的工具调用收费 $0.001，export_dataset 每写入一行收费 $0.0004。失败的调用、表头行和跳过的重复行均免费。每次启动服务收费 $0.00005。与任何 Apify Standby Actor 一样，Apify 还会对 Agent 连接期间以及连接后短暂空闲期间的运行平台用量收费（服务运行时占用 256 MB，因此每个会话只需不到一美分）。密钥通过 HTTPS 传输到你自己的运行实例中，仅保存在内存里，绝不会记录或存储。

连接：自行托管

需要 Node.js 24 或更高版本。

git clone https://github.com/joshuawhite389/google-sheets-mcp && cd google-sheets-mcp
npm install
PORT=3000 npm run serve

然后将客户端指向 http://localhost:3000/mcp，并设置 X-Google-Service-Account-Key 标头（无需 Apify 令牌；此时 export_dataset 会从本地 ./storage 文件夹读取数据集）。Dockerfile 会为 Apify 构建相同的服务；若要在其他地方运行，请设置 APIFY_META_ORIGIN=STANDBY 和 ACTOR_WEB_SERVER_PORT。

值得了解的限制

• Google 允许每个电子表格最多包含 1,000 万个单元格，每个单元格最多包含 50,000 个字符。
• 服务账号使用 Google 的标准配额：每分钟 60 个写入请求。遇到速率限制和 Google 服务异常时， 会通过退避机制重试。

开发

npm test          # unit tests against a fake Google API that verifies the signed sign-in
npm run e2e       # the real server process, driven by a real MCP client, against the fake Google
npm run typecheck

相关项目

Dataset to Pinecone & Qdrant Vector Export（一个 Apify Actor， 而非 MCP 服务）可将抓取的数据集分块并生成嵌入，导出到你自己的 Pinecone 或 Qdrant 索引中。

许可证

MIT