mcp-google-sheets-full

mcp-google-sheets-full

能实现 Sheets API 所有功能的 Google Sheets MCP 服务。

26 个工具涵盖读取/写入、结构性 batchUpdate、Drive 搜索，以及一个备用接口（run_sheets_script），可执行任意 Node.js 代码，并预先注入 sheets / drive / auth / spreadsheetId。支持两种身份验证模式：OAuth（默认，使用你自己的 Google 账号，无需为每个电子表格单独设置）或服务账号（可选，适用于无头环境 / CI）。

为什么选择此服务

大多数 Google Sheets MCP 服务只提供一组选定操作，到此为止。如果你需要它们未预想到的功能（特定的条件格式请求、多步骤迁移、Drive 端操作、先分析再写入的工作流），就会无计可施。

此服务补上了缺失的基础功能：run_sheets_script。传入一段 Node 代码，即可获得执行结果。Sheets v4 和 Drive v3 客户端已完成身份验证，并可直接使用。临时文件始终会被清理。

	mcp-google-sheets-full	freema/mcp-gsheets	xing5/mcp-google-sheets	ringo380/claude-google-sheets-mcp
读取 / 写入 / 追加 / 清除	✅	✅	✅	✅
结构性 batchUpdate（原始）	✅	部分支持	❌	❌
工作表标签页 / 行 / 格式 / 边框的精细操作	✅	✅	部分支持	❌
Drive 搜索（list / search_spreadsheets）	✅	❌	部分支持	❌
任意代码执行（run_sheets_script）	✅	❌	❌	❌
身份验证模式	✅ 默认 OAuth + 可选服务账号	优先使用服务账号	两者均支持	两者均支持
语言	TypeScript / Node	TypeScript / Node	Python	Python

每个工具的 spreadsheetId 始终是显式参数——没有隐藏的默认值。

安全模型

run_sheets_script 会在 MCP 服务运行的机器上，以你的用户账号身份，使用你的 OAuth 令牌执行 Node 代码。信任边界与任何允许 Claude 代表你运行代码的工具（Bash、Edit、Write）相同：

• 脚本只能执行 OAuth 范围允许的操作（Sheets + Drive）。它无法访问你的其他 Google 服务、tmpdir 以外的文件系统，也无法通过宿主 Node 进程不能使用的方式访问网络。
• 每个脚本都会在 os.tmpdir() 中获得一个新的临时文件，通过 node 执行，并在完成后删除（无论成功或失败）。
• 每次调用都有超时限制（默认 2 分钟，最长 10 分钟）。
• 令牌不会离开磁盘：OAuth 文件存放在 ~/.mcp-google-sheets/。

如果你不放心执行代码，只需不要调用 run_sheets_script——其余 25 个工具无需执行代码即可满足常见需求。

面向 AI Agent

如果你是正在为用户安装或运行此服务的 AI Agent（Claude Code、Cursor 等），请阅读 AGENTS.md。其中包含规范的逐步设置流程、工具选择指南、常见故障模式，以及信任与安全预期。

设置（一次性）

1. 安装

npm install -g mcp-google-sheets-full

这会将一个 mcp-google-sheets-full 可执行文件放到你的 PATH 中。更新：重新运行相同的命令。移除：npm uninstall -g mcp-google-sheets-full。

开发环境设置：克隆仓库并运行 npm install && npm run build。

2. 选择身份验证模式

此服务有两种身份验证方式。请根据使用方式只选择一种。

	OAuth（默认）	服务账号
最适合	笔记本电脑上的 Claude Desktop / Code / Cursor	CI、cron、无服务器、无头自动化
设置工作量	~/.mcp-google-sheets/ 中的 1 个文件	任意位置的 1 个文件 + 1 个环境变量
使用身份	你（你的 Google 账号）	机器人身份
可访问范围	你能访问的所有电子表格	仅明确共享给机器人邮箱的电子表格
是否需要浏览器？	需要（首次调用时进行一次）	从不需要
令牌刷新	自动	不适用

身份验证模式会自动选择：如果已设置环境变量 GOOGLE_APPLICATION_CREDENTIALS，服务将使用服务账号模式；否则将使用 OAuth 模式。

OAuth 设置

1. 前往 https://console.cloud.google.com/，创建或选择一个项目。

2. API 和服务 → 库：启用 Google Sheets API 和 Google Drive API。

3. API 和服务 → OAuth 同意屏幕：设置一个“External”应用（如果你使用 Workspace，也可以选择“Internal”）。将自己添加为测试用户。

4. API 和服务 → 凭据 → 创建凭据 → OAuth 客户端 ID：

   • 应用类型：桌面应用。
   • 名称：任意。

5. 下载 JSON 文件。

6. 将其保存到：

   • Windows：%USERPROFILE%\.mcp-google-sheets\gdrive-credentials.json
   • macOS / Linux：~/.mcp-google-sheets/gdrive-credentials.json

   （可通过环境变量 GSHEETS_CONFIG_DIR 覆盖目录。）

首次运行任何工具时，服务会打开浏览器以授予访问权限。生成的令牌会与凭据保存在同一目录下的 gdrive-token.json 中。之后的运行会在后台自动刷新。如果刷新失败（例如令牌已撤销），请删除 gdrive-token.json，下次调用时会重新触发浏览器授权流程。

服务账号设置（可选，无头模式）

1. 在 Google Cloud Console 中，为你的项目启用 Google Sheets API 和 Google Drive API（与 OAuth 设置相同）。
2. IAM 和管理 → 服务账号 → 创建服务账号。为其命名；对于我们的使用场景，无需在项目级别分配角色。
3. 打开服务账号 → 密钥 → 添加密钥 → JSON。下载文件。
4. 将文件放在任何可读取的位置（例如 ~/.mcp-google-sheets/sa-key.json 或 CI 密钥路径）。
5. 启动服务时设置环境变量：
   • Shell：export GOOGLE_APPLICATION_CREDENTIALS=/absolute/path/to/sa-key.json
   • Claude 配置：将其添加到服务条目下（见下文）。
6. 将你希望服务访问的每个电子表格分享给服务账号的邮箱地址（可在密钥 JSON 中查看 client_email，格式类似 [email protected]）。否则，即使凭据有效，调用也会返回 403。

此模式下不会生成令牌文件；服务会按需获取新的访问令牌。无需浏览器授权流程。

注册服务

全局安装后，mcp-google-sheets-full 二进制文件会位于 PATH 中。

Claude Code（项目或用户范围）

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

Claude Desktop（claude_desktop_config.json）

OAuth 模式（默认）：

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

服务账号模式——添加环境变量，将服务切换为无头身份验证：

{
  "mcpServers": {
    "google-sheets": {
      "command": "mcp-google-sheets-full",
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/sa-key.json"
      }
    }
  }
}

如果 Claude Desktop 找不到命令（在 macOS/Windows 上有时会忽略 PATH），请使用 npm bin -g 输出的绝对路径，并在其后添加 /mcp-google-sheets-full（Windows 上为 .cmd）。

可识别的环境变量：

• GOOGLE_APPLICATION_CREDENTIALS — 如果设置为服务账号 JSON 密钥路径，服务会切换到服务账号模式。未设置时则使用 OAuth 模式。
• GSHEETS_CONFIG_DIR — 覆盖 OAuth 凭据/令牌所在的目录（默认值：~/.mcp-google-sheets）。

使用 run_sheets_script

当调用方需要执行便捷工具未涵盖的操作（多步操作、自定义 batchUpdate 组合、Drive 操作、临时分析）时，会传入一段 Node 代码。运行环境会预先创建经过身份验证的上下文，因此脚本本身只需使用 sheets、drive、spreadsheetId。将值赋给 result 即可返回结构化结果。

示例代码：

// List all tabs and their first row
const meta = await sheets.spreadsheets.get({ spreadsheetId });
const headers = {};
for (const s of meta.data.sheets) {
  const r = await sheets.spreadsheets.values.get({
    spreadsheetId,
    range: `${s.properties.title}!1:1`,
  });
  headers[s.properties.title] = r.data.values?.[0] ?? [];
}
result = headers;

运行环境会将代码包装在异步 IIFE 中，因此可以直接使用顶层 await。错误会连同堆栈跟踪和非零退出码一起报告。无论执行结果如何，临时文件都会被删除。

提供的工具

工具	用途
auth_status	查看服务从哪里查找凭据/令牌，以及它们是否存在。
resolve_url	从 Google Sheets URL 中提取 spreadsheetId + gid。
list_spreadsheets	列出用户 Drive 中的电子表格（按最近使用时间倒序）。
search_spreadsheets	按名称子字符串或全文内容搜索电子表格。
get_spreadsheet	获取电子表格元数据（工作表、gridProperties）。
get_values	读取一个 A1 范围。
batch_get_values	读取多个范围。
update_values	将二维数组写入一个范围。
batch_update_values	一次调用写入多个范围。
append_values	在表格末尾追加行。
clear_values	清除一个或多个范围。
batch_update	结构性更改（原始 Sheets API Request[]）——用于处理任何没有专用工具支持的 Request 类型。
create_spreadsheet	创建一个归用户所有的新电子表格。
add_sheet / delete_sheet / duplicate_sheet / rename_sheet	管理工作表（接受 sheet_id gid 或 sheet_name）。
insert_rows / insert_columns / delete_rows / delete_columns	按从 0 开始的索引范围管理行/列。
merge_cells / unmerge_cells	合并范围（MERGE_ALL / MERGE_COLUMNS / MERGE_ROWS）。
format_cells	对范围应用部分 CellFormat（背景、textFormat、对齐方式、numberFormat，等等）。
set_borders	为范围设置边框（top/bottom/left/right/innerHorizontal/innerVertical）。
run_sheets_script	使用预先完成身份验证的 sheets/drive/auth/spreadsheetId 运行任意 Node 代码。

备注

• 初次授权期间，OAuth 流程会监听 http://localhost:3456。请确保该端口未被占用。
• 请求的范围：https://www.googleapis.com/auth/spreadsheets 和 https://www.googleapis.com/auth/drive。
• 每次调用 run_sheets_script 都会启动一个全新的 node 进程。它会重复使用同一份 ~/.mcp-google-sheets/ 凭据和令牌。超时时间可配置（默认 2 min，最长 10 min）。