Google表格MCP服务器

A. 模型上下文协议（MCP） 该服务器使MCP客户端能够安全地本地访问您的Google表格，以读取、写入、格式化和管理电子表格数据，并具有智能自动格式化、图表创建和令牌高效输出功能。

隐私说明： MCP服务器运行本地在你的机器上。Google表格数据直接从Google的API提取到您的计算机上，只有当您明确允许工具调用时，才会与Claude共享。

______________________________________________________________________

所得
先决条件
1）创建谷歌云项目
2）启用Google表格和驱动器API
3）配置OAuth同意屏幕
4）创建OAuth客户端凭据（桌面应用程序）
5）获取代码
6）安装Python依赖项
7）首次运行（授权和创建 token.json)
8）连接到克劳德桌面（MCP配置）
9）在Claude中使用它
工具参考
智能功能
安全提示
故障排除
卸载/删除
许可证（MIT）

______________________________________________________________________

所得

读写使用A1表示法将数据保存到任何Google表格范围(A1:C10, Sales!A:Z等等）。
自动格式化 智能检测并应用日期、货币、百分比和公式的格式。
附加数据 具有智能放置和页眉检测功能的纸张。
创建图表 （线、条、列、饼图、散点图）直接在电子表格中显示。
应用筛选器 并高效地执行批量操作。
压缩JSON 响应以最小化LLM令牌并提高性能。
智能缓存 以减少API调用并加快重复操作。
URL灵活性 -适用于完整的Google表格URL、短URL或直接的电子表格ID。

______________________________________________________________________

先决条件

具有Google表格访问权限的Google帐户。
python 3.8+ 安装。
您选择的MCP主机。本指南是为Claude Desktop（macOS或Windows）配置的。

______________________________________________________________________

1）创建谷歌云项目

打开谷歌云控制台并登录：

https://console.cloud.google.com/

创建项目：

https://console.cloud.google.com/projectcreate 为其命名（例如。， 谷歌表格MCP).在顶部栏中注意所选项目。

______________________________________________________________________

2）启用Google表格和驱动器API

选择项目后，打开Google Sheets API页面：

https://console.cloud.google.com/apis/library/sheets.googleapis.com

点击启用.

同时启用Google Drive API（电子表格元数据所需）：

https://console.cloud.google.com/apis/library/drive.googleapis.com

点击启用.

______________________________________________________________________

3）配置OAuth同意屏幕

转到OAuth同意屏幕：

https://console.cloud.google.com/apis/credentials/consent

用户类型： 选择外部.
集 发布状态 向测试.
在...之下 测试用户，单击 添加用户 并添加将使用此应用程序的Google帐户（通常只有您自己的帐户）。
填写 应用程序名称, 用户支持电子邮件，以及 开发人员联系信息。保存。

使用测试模式与 测试用户 避免了个人使用的漫长应用程序验证过程。所请求的Google表格范围被认为是“敏感的”，这是意料之中的。

______________________________________________________________________

4）创建OAuth客户端凭据（桌面应用程序）

首选凭证:

https://console.cloud.google.com/apis/credentials

点击 创建凭据→ OAuth客户端ID.
应用程序类型： 选择 桌面应用程序 （建议使用本地工具）。
创建后，单击 下载JSON 并保存它旁边 gsheets_mcp.py 像 client_secret.json.

重要提示： 使用 桌面应用程序“Web应用程序”经常导致本地工具的重定向错误。

______________________________________________________________________

5）获取代码

# clone this repo (or download ZIP and extract)
git clone https://github.com/yourname/gsheets-mcp.git
cd gsheets-mcp

放置您下载的 client_secret.json 在此文件夹中（与 gsheets_mcp.py). 应用程序将创建 token.json 在您首次登录后。

不要泄露秘密。 两个文件都已在 .gitignore: `` client_secret.json token.json ``

______________________________________________________________________

6）安装Python依赖项

安装要求

macOS/Linux

python3 -V
python3 -m venv .venv
source .venv/bin/activate

pip install --upgrade pip
pip install -r requirements.txt

Windows（PowerShell）

py -3 -V
py -3 -m venv .venv
.\.venv\Scripts\Activate.ps1

python -m pip install --upgrade pip
pip install -r requirements.txt

______________________________________________________________________

7）首次运行（授权和创建 `token.json`)

运行服务器一次以完成Google登录和写入 token.json:

macOS/Linux

source .venv/bin/activate
python3 gsheets_mcp.py

Windows（PowerShell）

.\.venv\Scripts\Activate.ps1
python .\gsheets_mcp.py

您的浏览器会打开一个谷歌登录/同意页面。
批准请求的范围，以允许服务器代表您访问您的Google表格。
成功之后， token.json 在脚本旁边创建。请确保此文件的安全性和私密性。

如果你看到a redirect_uri_mismatch 错误，您可能创建了 Web应用程序 OAuth客户端而不是 桌面应用程序.创建新 桌面应用程序 客户端并下载为 client_secret.json.

您可以在看到“Google Sheets MCP Server starting…”日志消息后关闭终端。

______________________________________________________________________

8）连接到克劳德桌面（MCP配置）

Claude Desktop读取名为的JSON配置文件 claude_desktop_config.json.

配置文件在哪里？

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
窗户： %APPDATA%\Claude\claude_desktop_config.json

在Claude Desktop中，您还可以从以下位置打开此文件 设置→ 开发者→ 编辑配置.

最小配置示例

macOS

{
  "mcpServers": {
    "gsheets-mcp": {
      "command": "python3",
      "args": ["/ABSOLUTE/PATH/TO/gsheets_mcp.py"],
      "env": {
        "PYTHONIOENCODING": "utf-8",
        "GSHEETS_CACHE_TTL": "300"
      }
    }
  }
}

视窗

{
  "mcpServers": {
    "gsheets-mcp": {
      "command": "python",
      "args": ["C:\\\\ABSOLUTE\\\\PATH\\\\TO\\\\gsheets_mcp.py"],
      "env": {
        "PYTHONIOENCODING": "utf-8",
        "GSHEETS_CACHE_TTL": "300"
      }
    }
  }
}

可选环境变量

GSHEETS_CACHE_TTL：缓存超时时间（秒）（默认值：300）
GSHEETS_TOKEN_FILE：token.json文件的自定义路径
GSHEETS_CREDENTIALS_FILE：client_secret.json文件的自定义路径
GSHEETS_DEBUG：设置为“true”用于调试日志记录

保存配置后， 完全退出并重新启动 克劳德桌面。您应该看到MCP锤子图标，指示服务器可用。

______________________________________________________________________

9）在Claude中使用它

尝试以下提示：

“从我的销售电子表格中的单元格A1:E10读取数据并分析趋势。”
“根据‘Q4结果’表中A1:C5范围内的数据创建条形图。”
“将这些新的销售记录添加到我的跟踪电子表格的底部。”
“应用筛选器，仅显示列C包含“已完成”的行。”
“使用正确的美元格式设置货币列的格式。”
“写一个公式来计算D列的总和。”

每次工具调用前，Claude都会征求您的批准。

______________________________________________________________________

工具参考

所有输出都使用紧凑的JSON和高效的数据结构，以减少LLM令牌并提高性能。

`read_range`

通过自动发现电子表格结构从Google表格区域读取单元格值。

参数：

spreadsheet_url （必填）：谷歌表格URL或电子表格ID
sheet_name （可选）：工作表名称（如果省略，则使用第一张工作表）
range （必填）：A1符号范围（例如，“A1:C10”、“A:A”）
include_formatting （可选）：包含单元格格式信息（默认值：false）

示例响应：

{
  "values": [
    ["Name", "Price", "Date"],
    ["Product A", 29.99, "2024-01-15"],
    ["Product B", 39.99, "2024-01-16"]
  ],
  "range": "Sheet1!A1:C3",
  "majorDimension": "ROWS"
}

`write_range`

使用智能自动格式化将值写入/更新到指定范围。

参数：

spreadsheet_url （必填）：谷歌表格URL或电子表格ID
sheet_name （可选）：图纸名称
range （必填）：A1符号范围
values （必填）：二维值数组
auto_format （可选）：自动检测并应用格式（默认值：true）
value_input_option （可选）：“RAW”或“USER_ENTERED”（默认值：“USER_ENTER”）

示例响应：

{
  "spreadsheetId": "1ABC123...",
  "updatedRange": "Sheet1!A1:C3",
  "updatedRows": 3,
  "updatedColumns": 3,
  "updatedCells": 9
}

`append_data`

通过智能放置和页眉检测在工作表末尾添加新行。

参数：

spreadsheet_url （必填）：谷歌表格URL或电子表格ID
sheet_name （可选）：图纸名称
data_rows （必需）：要追加的行数组
auto_format （可选）：自动检测格式（默认值：true）

示例响应：

{
  "spreadsheetId": "1ABC123...",
  "tableRange": "Sheet1!A1:D5",
  "updates": {
    "updatedRange": "Sheet1!A4:D5",
    "updatedRows": 2,
    "updatedColumns": 4,
    "updatedCells": 8
  }
}

`create_chart`

直接在电子表格中创建嵌入式图表。

参数：

spreadsheet_url （必填）：谷歌表格URL或电子表格ID
sheet_name （可选）：纸张放置图
chart_type （必填）：“LINE”、“BAR”、“COLUMN”、“PIE”或“SCATTER”
data_range （必填）：图表数据用A1表示法
title （可选）：图表标题
position （可选）：图表位置 {"row": 0, "col": 5}

示例响应：

{
  "chartId": 1234567890,
  "position": {"sheetId": 0, "overlayPosition": {"anchorCell": {"rowIndex": 0, "columnIndex": 5}}},
  "chartType": "COLUMN"
}

`apply_filter`

对具有列特定条件的数据区域应用基本筛选器。

参数：

spreadsheet_url （必填）：谷歌表格URL或电子表格ID
sheet_name （可选）：图纸名称
range （必填）：A1表示滤波器范围
column_filters （必填）：基于列的过滤条件

过滤条件：

TEXT_CONTAINS：文本包含值
TEXT_EQ：文本完全等于值
NUMBER_GREATER：数字大于值
NUMBER_LESS：数字小于值

请求示例：

{
  "column_filters": {
    "Status": {"condition": "TEXT_CONTAINS", "value": "Completed"},
    "Amount": {"condition": "NUMBER_GREATER", "value": "100"}
  }
}

`batch_update`

在单个请求中高效执行多个操作。

参数：

spreadsheet_url （必填）：谷歌表格URL或电子表格ID
operations （必填）：要执行的操作数组

支持的操作：

clear_range：清除单元格内容
sort_range：对数据范围进行排序
format_cells：应用单元格格式
merge_cells：合并单元格范围
create_sheet：添加新工作表
delete_sheet：删除图纸

示例响应：

{
  "spreadsheetId": "1ABC123...",
  "replies": [
    {"addSheet": {"properties": {"sheetId": 123, "title": "New Sheet"}}},
    {"updateCells": {"updatedRows": 5, "updatedColumns": 3}}
  ]
}

______________________________________________________________________

智能功能

自动格式检测

MCP会自动检测并为不同的数据类型应用适当的格式：

日期：识别“2024-01-15”、“2024年1月15日”、“2023年1月5日”等格式
货币：处理具有正确数字格式的“$1234.56”格式
百分比：使用百分比格式将“15.5%”转换为十进制值
数字：处理带有千位分隔符的数值
公式：识别以“=”开头的Excel/表格公式并保留它们
文本：保留文本格式并处理特殊字符

智能缓存系统

电子表格元数据 默认情况下缓存5分钟（可配置）
结构发现 缓存以避免对工作表名称和范围重复调用API
自动缓存失效 当数据被修改时
内存效率高 清理过期的缓存条目
减少API配额使用 对于重复操作来说意义重大

URL处理灵活性

自动接受各种Google表格URL格式：

Full URL: https://docs.google.com/spreadsheets/d/1ABC123.../edit#gid=0
Short URL: https://docs.google.com/spreadsheets/d/1ABC123...
Direct ID: 1ABC123...

智能范围扩展

自动检测数据边界 当使用像“A:A”这样的部分范围时
处理合并的单元格 智能地
保留格式 跨范围作战
优化API调用 通过批处理范围请求

______________________________________________________________________

安全提示

保持 client_secret.json 和 token.json 私有的.做不将它们提交到Git。

包含的文件会自动排除这两个文件 .gitignore.

向撤销访问：

- 删除 token.json 并再次运行服务器以稍后重新同意，或 - 访问Google帐户权限并删除应用程序： https://myaccount.google.com/permissions

请求的范围（最低必要权限）：

- https://www.googleapis.com/auth/spreadsheets （读/写谷歌表格） - https://www.googleapis.com/auth/drive.metadata.readonly （仅读取电子表格元数据）

______________________________________________________________________

故障排除

重定向URI不匹配 你可能创造了一个 Web应用程序 OAuth客户端。做一个 桌面应用程序 OAuth客户端并下载为 client_secret.json.

“此应用程序被阻止”或缺少作用域 将OAuth同意屏幕保留在测试并在下面添加您的帐户 测试用户.

403/权限不足

删除 token.json 并再次运行服务器以使用最新范围重新同意。
确保Google帐户对您尝试修改的电子表格具有编辑权限。
检查Google Sheets API和Drive API是否已在您的项目中启用。

“找不到电子表格”错误

验证电子表格URL或ID是否正确。
确保电子表格与您的Google帐户共享。
检查电子表格是否未被删除或移至垃圾箱。

克劳德看不到服务器

编辑配置后重新启动Claude Desktop。
仔细检查绝对路径和JSON语法 claude_desktop_config.json.
在Windows上，确保 PYTHONIOENCODING=utf-8 如示例所示进行设置。
检查Python和所有依赖项是否已正确安装。

自动格式化不起作用

确保 auto_format=true 已设置（默认）。
检查一下 value_input_option="USER_ENTERED" 已使用（默认）。
某些格式可能需要您的Google表格中的特定区域设置。

超出费率限制/配额

服务器实现智能缓存，以最大限度地减少API调用。
如果达到配额，请等待几分钟或增加缓存TTL。
考虑对多个更改使用批处理操作。

图表创建失败

确保数据范围包含图表类型的有效数字数据。
检查目标工作表是否存在，以及您是否具有编辑权限。
饼图只需要2列（标签和值）。

身份验证期间出现防火墙/浏览器问题 允许本地浏览器窗口打开 http://localhost: 回调。如果被阻止，暂时允许弹出窗口。

______________________________________________________________________

卸载/删除

删除 "gsheets-mcp" 阻止 claude_desktop_config.json 并重新启动克劳德桌面。
删除 token.json 并且可选 client_secret.json.
删除虚拟环境： rm -rf .venv （macOS/Linux）或 rmdir /s .venv （Windows）。
如果需要，在您的Google帐户权限中撤销应用程序：

https://myaccount.google.com/permissions

______________________________________________________________________

许可证（MIT）

特此免费授予任何获得本软件和相关文档文件（“软件”）副本的人处理软件的权限 没有限制，包括但不限于以下权利 使用、复制、修改、合并、发布、分发、再许可和/或出售 软件的副本，并允许软件提供给的人这样做，但须符合以下条件：

软件按“原样”提供，不提供任何形式的保证明示或暗示的，包括但不限于适销性、特定用途适用性和不侵权的保证。 在任何情况下，作者或版权持有人均不承担责任 对于因软件或软件的使用或其他交易而产生或与之相关的任何索赔、损害赔偿或其他责任，无论是在合同、侵权或其他诉讼中。

Gsheets MCP

快速接入

详细介绍

Google表格MCP服务器

目录

所得

先决条件

1） 创建谷歌云项目

2） 启用Google表格和驱动器API

3） 配置OAuth同意屏幕

4） 创建OAuth客户端凭据（桌面应用程序）

5） 获取代码

6） 安装Python依赖项

macOS/Linux

Windows（PowerShell）

7） 首次运行（授权和创建 token.json)

macOS/Linux

Windows（PowerShell）

8） 连接到克劳德桌面（MCP配置）

最小配置示例

可选环境变量

9） 在Claude中使用它

工具参考

read_range

write_range

append_data

create_chart

apply_filter

batch_update

智能功能

自动格式检测

智能缓存系统

URL处理灵活性

智能范围扩展

安全提示

故障排除

卸载/删除

许可证（MIT）

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

1）创建谷歌云项目

2）启用Google表格和驱动器API

3）配置OAuth同意屏幕

4）创建OAuth客户端凭据（桌面应用程序）

5）获取代码

6）安装Python依赖项

7）首次运行（授权和创建 `token.json`)

8）连接到克劳德桌面（MCP配置）

9）在Claude中使用它

`read_range`

`write_range`

`append_data`

`create_chart`

`apply_filter`

`batch_update`