MCP Google Sheets 服务器

从 Claude Desktop、Claude Code 以及任何兼容模型上下文协议 (MCP) 的 AI 客户端读取、写入和管理 Google Sheets。

一个轻量级、生产就绪的模型上下文协议 (MCP) 服务器，将 Google Sheets API 暴露给 Claude 和其他 LLM 代理。自动化电子表格工作流，构建可记录到表格的 AI 代理工具，将数据管道与团队的电子表格同步，或者让 Claude 为你编辑文档——所有这些都通过一个 MCP 服务器完成。

目录

• 为什么

• 功能特性

• 快速开始

• 设置

  • 1. 创建 Google Cloud 项目

  • 2. 启用 Sheets API

  • 3. 创建 OAuth 2.0 凭据

  • 4. 安装服务器

  • 5. 授权

• 注册到你的 MCP 客户端

  • Claude Desktop

  • Claude Code

• 可用工具

• 使用示例

• 配置

• 安全

• 故障排除

• 开发

• 许可证

为什么

如果你曾希望 Claude 能更新 Google Sheet——无论是工作追踪表、习惯记录表还是项目仪表盘——而无需切换窗口，那么这个服务器为你提供了缺失的工具。它是 Anthropic 官方 Google Drive MCP 连接器（该连接器可读取文件但无法写入单元格）的自然对应物。

常见工作流：

• 让 Claude 在你申请工作时向求职追踪表追加行

• 同步研究阅读列表、每周回顾或雅思学习日志

• 为 AI 代理提供结构化的、可审计的输出到电子表格

• 通过自然语言提示自动化财务或运营仪表盘

功能特性

• ✅ 读取 A1 表示法中的任意范围

• ✅ 更新 单元格值，支持 RAW 或 USER_ENTERED 解析

• ✅ 追加 行到任意工作表（非常适合日志记录）

• ✅ 清除 范围而不删除格式

• ✅ 批量更新 一次调用中更新多个范围

• ✅ 检查 电子表格元数据（工作表标签、维度）

• 🔐 OAuth 2.0，支持本地令牌存储和自动刷新

• 📦 TypeScript、ES 模块、最小依赖

• 🖥️ 可与 Claude Desktop、Claude Code 以及任何通过 stdio 的 MCP 客户端配合使用

快速开始

# 1. Clone
git clone https://github.com/yangchoi/mcp-google-sheets.git
cd mcp-google-sheets

# 2. Install and build
npm install
npm run build

# 3. Put your Google Cloud OAuth credentials.json here
mkdir -p ~/.config/mcp-google-sheets
cp /path/to/downloaded-credentials.json ~/.config/mcp-google-sheets/credentials.json

# 4. Authorize (opens browser once)
npm run auth

# 5. Register with Claude — see below

设置

1. 创建 Google Cloud 项目

• 打开 Google Cloud Console。

• 点击新建项目 → 任意命名（例如 mcp-sheets）。

2. 启用 Sheets API

• 在你的项目中，打开 Google Sheets API。

• 点击启用。

3. 创建 OAuth 2.0 凭据

• 打开 凭据。

• 点击创建凭据 → OAuth 客户端 ID。

• 如果提示，先配置 OAuth 同意屏幕：

  • 用户类型：外部（除非你使用的是具有内部选项的 Workspace）

  • 在应用处于测试模式时，将你自己添加为测试用户

  • 同意屏幕上的范围可以留空；应用会在运行时请求它们

• 回到创建 OAuth 客户端 ID：

  • 应用类型：桌面应用

  • 名称：任意（例如 mcp-google-sheets）

• 点击下载 JSON 并保存。这就是你的 credentials.json。

将文件移动到默认配置目录：

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

（或者设置 GOOGLE_SHEETS_CREDENTIALS_PATH 指向其他位置——参见配置。）

4. 安装服务器

git clone https://github.com/yangchoi/mcp-google-sheets.git
cd mcp-google-sheets
npm install
npm run build

5. 授权

运行一次性 OAuth 流程。你的浏览器将打开，你批准访问你自己的 Sheets，生成的令牌将存储在 ~/.config/mcp-google-sheets/token.json。

npm run auth

你应该在终端中看到 Authorization complete. Token saved.。

注册到你的 MCP 客户端

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）并添加：

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

重启 Claude Desktop。Sheets 工具将出现在工具选择器中。

Claude Code

添加到你的 Claude Code MCP 配置（通常在 ~/.claude/settings.json 的 mcpServers 下）：

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

重启 Claude Code。通过 /mcp 确认工具已加载。

可用工具

所有工具都接受 spreadsheetId（可在工作表 URL 中的 /d/ 和 /edit 之间找到）。

使用示例

提示 Claude：

“查看电子表格 1abcXYZ...，并向 Applications 工作表添加新行：Legora, Stockholm, Legal AI, 2026-08-18, pending。”

Claude 将调用 get_spreadsheet_metadata 找到工作表，然后使用这些值调用 append_row。

或者读取 + 总结：

“读取 1abcXYZ... 中 Applications 工作表的前 20 行，并告诉我还有多少行处于 pending 状态。”

Claude 调用 read_range 读取 Applications!A1:F20，然后对返回的数组进行推理。

配置

环境变量（全部可选）：

安全

• credentials.json 和 token.json 仅本地存储，除发送到 Google 的 OAuth 服务器外，不会传输到任何地方。

• 这两个文件都包含在 .gitignore 中；不要将它们提交到版本控制。

• 服务器仅请求 spreadsheets 范围——没有 Drive 范围的访问权限，没有 Gmail，没有日历。

• 令牌自动刷新；不会暴露长期有效的访问令牌。

• 运行服务器在稳定状态下不需要任何网络监听端口（临时端口 47319 仅在初始 OAuth 回调期间使用，之后立即关闭）。

故障排除

credentials.json not found —— 你错过了步骤 3–4。检查路径。

OAuth 期间出现 Error: access_denied —— 你的 Google 帐户未在 OAuth 同意屏幕上列为测试用户。转到 OAuth 同意屏幕 → 在测试用户下添加你的电子邮件。

调用工具时出现 insufficient permission —— 令牌创建时范围较小。删除 token.json 并重新运行 npm run auth。

工具未出现在 Claude 中 —— 确认 MCP 配置中的路径是绝对路径，并且指向 dist/index.js（而不是 src/index.ts）。确保你运行了 npm run build。

服务器启动时出现 No stored token —— 你跳过了步骤 5。运行 npm run auth。

开发

npm install
npm run dev      # tsc --watch
npm run build    # produces dist/
npm run start    # runs dist/index.js on stdio

欢迎贡献。这是一个最小核心；欢迎提交关于结构化更新（spreadsheets.batchUpdate 用于格式化、添加工作表、筛选器、受保护范围）的 PR。

许可证

MIT