Google Sheets MCP Server

什么是 Google Sheets MCP Server？

Google Sheets MCP Server（mcp-google-sheets）是一个开源的 Python MCP 服务器，可将 Claude、Cursor 等 MCP 客户端连接到 Google Sheets 和 Google Drive API，让 AI 助手能够列出、读取、写入、共享电子表格并生成图表。

它是由 xing5 开发的社区项目（MIT 许可证），以 mcp-google-sheets 发布在 PyPI 上，只需一条 uvx 命令即可启动。它并非 Google 官方出品。服务器本身不存储你的数据：所有操作都通过官方 Google Sheets 和 Drive API 完成，使用的是你自己掌控的凭据。

如何使用 Google Sheets MCP Server？

前置条件

1. 一个已启用 Google Sheets API 和 Google Drive API 的 Google Cloud 项目（APIs & Services → Library）。
2. 凭据。README 推荐使用服务账号：在 IAM & Admin → Service Accounts 中创建服务账号并下载 JSON 密钥，然后创建一个 Google Drive 文件夹，以 Editor 权限共享给该服务账号的 client_email。从文件夹 URL 中记下文件夹 ID（https://drive.google.com/drive/folders/<FOLDER_ID>）。
3. 安装 uv（它提供 uvx）：

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

环境变量

变量	方式	用途
SERVICE_ACCOUNT_PATH	服务账号	JSON 密钥文件路径
DRIVE_FOLDER_ID	服务账号	共享给服务账号的 Drive 文件夹 ID
CREDENTIALS_PATH / TOKEN_PATH	OAuth 2.0	OAuth 客户端 JSON 及令牌存储位置（默认 credentials.json / token.json）
CREDENTIALS_CONFIG	两者皆可	Base64 编码的凭据 JSON，适用于 Docker 或 CI
GOOGLE_APPLICATION_CREDENTIALS	ADC	Google 标准的应用默认凭据（Application Default Credentials）路径

服务器依次检查 CREDENTIALS_CONFIG、SERVICE_ACCOUNT_PATH、CREDENTIALS_PATH，最后回退到应用默认凭据。建议先在终端中测试：

export SERVICE_ACCOUNT_PATH="/path/to/your/service-account-key.json"
export DRIVE_FOLDER_ID="YOUR_DRIVE_FOLDER_ID"
uvx mcp-google-sheets@latest

README 建议始终使用 @latest；否则 uvx 可能运行缓存中的旧版本。

Claude Desktop

将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "google-sheets": {
      "command": "uvx",
      "args": ["mcp-google-sheets@latest"],
      "env": {
        "SERVICE_ACCOUNT_PATH": "/full/path/to/your/service-account-key.json",
        "DRIVE_FOLDER_ID": "your_shared_folder_id_here"
      }
    }
  }
}

如需改用 OAuth，将 env 块替换为 CREDENTIALS_PATH 和 TOKEN_PATH；首次使用时会打开浏览器进行 Google 登录。在 macOS 上如果看到 spawn uvx ENOENT，请把 command 设为完整路径，例如 /Users/yourusername/.local/bin/uvx。

Claude Code

使用 Claude Code CLI 注册同样的命令：

claude mcp add google-sheets \
  -e SERVICE_ACCOUNT_PATH=/full/path/to/your/service-account-key.json \
  -e DRIVE_FOLDER_ID=your_shared_folder_id_here \
  -- uvx mcp-google-sheets@latest

Cursor

将上面 Claude Desktop 中的 mcpServers JSON 块放入 ~/.cursor/mcp.json（全局）或 .cursor/mcp.json（项目级）。

Google Sheets MCP Server 的主要功能

• 直接集成 Google Sheets API 和 Google Drive API。
• 读写单元格值、公式、行、列和工作表的工具，支持批量读写。
• 电子表格管理：创建、列出、搜索、复制、重命名，并以 reader、commenter 或 writer 角色共享。
• 通过 add_chart 创建图表（柱形图、条形图、折线图、面积图、饼图、散点图、组合图、直方图）。
• 四种认证方式：服务账号、OAuth 2.0、Base64 凭据注入和应用默认凭据。
• 通过 --include-tools 或 ENABLED_TOOLS 过滤工具，减少完整工具集约 13K token 的上下文占用。
• 通过 uvx 免安装启动，并提供用于 SSE 部署的 Dockerfile。
• 提供 MCP 资源 spreadsheet://{spreadsheet_id}/info，用于获取电子表格基本元数据。

Google Sheets MCP Server 工具

• 查找： list_spreadsheets、search_spreadsheets、list_folders、list_sheets 和 get_multiple_spreadsheet_summary 用于查找文件，并预览标题、工作表、表头和前几行。
• 读取： get_sheet_data 以 A1 表示法读取区域（可选返回完整网格数据和格式），get_sheet_formulas 返回公式而非值，get_multiple_sheet_data 一次调用读取多个电子表格中的多个区域。另外还有 find_in_spreadsheet。
• 写入： update_cells 覆盖写入某个区域，batch_update_cells 一次写入多个区域，add_rows 和 add_columns 插入空行或空列，batch_update 用于更广泛的更新。
• 结构与共享： create_spreadsheet、create_sheet、copy_sheet、rename_sheet 和 share_spreadsheet 管理文件和访问权限；add_chart 基于数据区域生成图表。

README 推荐的最小工具子集是 get_sheet_data、update_cells、list_spreadsheets 和 list_sheets。

Google Sheets MCP Server 的使用场景

• 报表：“创建一个名为 'Quarterly Sales Report Q3' 的新电子表格，并添加一个 'Summary' 工作表。”
• 数据查询：“在 'Quarterly Sales Report' 电子表格中，读取 Sheet1 的 A1 到 E10 区域并总结趋势。”
• 任务跟踪：“在我的 'Project Tasks' 电子表格的 'Tasks' 工作表中，把 B2 单元格更新为 'In Progress'。”
• 智能体日志： Claude Code 每完成任务的一个步骤，就把结果行追加到 'Log' 工作表。
• 共享：“把 'Team Vacation Schedule' 电子表格以 reader 身份共享给 team@example.com，不要发送通知。”
• 图表：“在我的 'Sales Report' 电子表格中，用 A1:B13 的数据创建一个展示月度收入的柱形图。”

Google Sheets MCP Server 与替代方案对比

• MCP Google Sheets Server（freema/mcp-gsheets） 是基于 Node.js 的替代方案，同样使用服务账号；如果你更喜欢基于 npm 的安装方式，可以选择它。
• Google Sheets MCP Server（mkummer225） 是一个更早、规模更小的社区项目。
• Google Drive MCP 侧重于搜索和读取 Drive 文件，而不是编辑电子表格单元格。

其中，xing5 的 mcp-google-sheets 在 GitHub 上关注者最多、Sheets 工具集最全，因此通常是搭建 Google Sheets MCP 的首选。

Google Sheets MCP Server 常见问题排查

• macOS 上出现 spawn uvx ENOENT： 客户端找不到 uvx。请使用完整路径，例如 /Users/yourusername/.local/bin/uvx。
• list_spreadsheets 中看不到电子表格： 使用服务账号时，只能看到共享给该服务账号邮箱（并在 DRIVE_FOLDER_ID 中设置）的文件夹中的文件。请以 Editor 权限把文件夹或文件共享给该 client_email。
• 权限或 API 错误： 确认 Google Sheets API 和 Google Drive API 都已在凭据所属的同一个 Cloud 项目中启用。
• 更新后仍是旧行为： 运行 uvx mcp-google-sheets@latest；不加 @latest 时，uvx 可能继续使用缓存版本。
• 上下文窗口被占满： 用 --include-tools 或 ENABLED_TOOLS 限制工具，以英文逗号分隔且不含空格。