googlesheets-automation

通过 Rube MCP 自动化 Google Sheets

通过 Composio 的 Google Sheets 工具包，自动化 Google Sheets 工作流，包括读取和写入数据、管理电子表格和工作表标签、设置单元格格式、筛选行，以及新增或更新记录。

工具包文档：composio.dev/toolkits/googlesheets

前提条件

• 必须连接 Rube MCP（可用 RUBE_SEARCH_TOOLS）
• 通过 RUBE_MANAGE_CONNECTIONS 建立有效的 Google Sheets 连接，工具包为 googlesheets
• 始终先调用 RUBE_SEARCH_TOOLS，获取最新的工具架构

设置

获取 Rube MCP：在客户端配置中将 https://rube.app/mcp 添加为 MCP 服务。无需 API 密钥，只需添加端点即可使用。

1. 确认 RUBE_SEARCH_TOOLS 能够响应，以验证 Rube MCP 是否可用
2. 调用 RUBE_MANAGE_CONNECTIONS，并指定工具包 googlesheets
3. 如果连接状态不是 ACTIVE，请按照返回的授权链接完成 Google OAuth
4. 运行任何工作流之前，确认连接状态为 ACTIVE

核心工作流

1. 读取和写入数据

适用场景：用户希望从 Google Sheet 读取数据或向其中写入数据

工具调用顺序：

1. GOOGLESHEETS_SEARCH_SPREADSHEETS - 如果不知道 ID，按名称查找电子表格［前置条件］
2. GOOGLESHEETS_GET_SHEET_NAMES - 列出工作表标签名称，以确定目标工作表［前置条件］
3. GOOGLESHEETS_BATCH_GET - 读取一个或多个范围中的数据［必需］
4. GOOGLESHEETS_BATCH_UPDATE - 向某个范围写入数据或追加行［必需］
5. GOOGLESHEETS_VALUES_UPDATE - 更新单个指定范围［替代方案］
6. GOOGLESHEETS_SPREADSHEETS_VALUES_APPEND - 在表格末尾追加行［替代方案］

关键参数：

• spreadsheet_id：电子表格 URL 中的字母数字 ID（位于 '/d/' 和 '/edit' 之间）
• ranges：A1 表示法数组（例如，'Sheet1!A1:Z1000'）；始终使用有界范围
• sheet_name：工作表标签名称（支持不区分大小写的匹配）
• values：二维数组，其中每个内部数组代表一行
• first_cell_location：以 A1 表示法指定的起始单元格（省略则追加）
• valueInputOption：'USER_ENTERED'（解析输入）或 'RAW'（按字面值处理）

注意事项：

• 工作表标签名称大小写不符或不存在时，会报错 "Sheet 'X' not found"
• 空范围可能不包含 valueRanges[i].values；若缺失，应视为空数组
• 即使只写入一行，GOOGLESHEETS_BATCH_UPDATE 的值也必须是二维数组（列表的列表）
• 对于超过 10,000 行的工作表，无界范围（如 'A:Z'）可能导致超时；始终使用行数限制来界定范围
• 追加操作会根据检测到的 tableRange 进行；请使用返回的 updatedRange 验证位置

2. 创建和管理电子表格

适用场景：用户希望创建新的电子表格或管理其中的工作表标签

工具调用顺序：

1. GOOGLESHEETS_CREATE_GOOGLE_SHEET1 - 创建新的电子表格［必需］
2. GOOGLESHEETS_ADD_SHEET - 添加新的工作表标签／工作表［必需］
3. GOOGLESHEETS_UPDATE_SHEET_PROPERTIES - 重命名、隐藏、重新排序或设置工作表标签颜色［可选］
4. GOOGLESHEETS_GET_SPREADSHEET_INFO - 获取完整的电子表格元数据［可选］
5. GOOGLESHEETS_FIND_WORKSHEET_BY_TITLE - 检查指定的工作表标签是否存在［可选］

关键参数：

• title：电子表格或工作表标签名称
• spreadsheetId：目标电子表格 ID
• forceUnique：如果工作表标签名称已存在，则自动追加后缀（默认值为 true）
• properties.gridProperties：设置行数、列数和冻结行

注意事项：

• 同一电子表格中的工作表标签名称必须唯一
• 默认工作表名称取决于区域设置（英文为 'Sheet1'，西班牙语为 'Hoja 1'）
• 并行创建多个工作表时不要使用 index（会导致 'index too high' 错误）
• 如果账户没有访问权限，GOOGLESHEETS_GET_SPREADSHEET_INFO 可能返回 403

3. 搜索和筛选行

适用场景：用户想查找特定行或筛选工作表数据

工具调用顺序：

1. GOOGLESHEETS_LOOKUP_SPREADSHEET_ROW - 查找与单元格值完全匹配的首行 [必需]
2. GOOGLESHEETS_SET_BASIC_FILTER - 对某个范围应用筛选/排序 [替代方案]
3. GOOGLESHEETS_CLEAR_BASIC_FILTER - 移除现有筛选条件 [可选]
4. GOOGLESHEETS_BATCH_GET - 读取筛选结果 [可选]

关键参数：

• query：要匹配的确切文本值（匹配整个单元格内容）
• range：要搜索的 A1 表示法范围
• case_sensitive：是否区分大小写的布尔值（默认值为 false）
• filter.range：包含 sheet_id 的基本筛选网格范围
• filter.criteria：基于列的筛选条件
• filter.sortSpecs：排序规范

注意事项：

• GOOGLESHEETS_LOOKUP_SPREADSHEET_ROW 匹配整个单元格内容，而不是子字符串
• 名称中带空格的工作表必须在范围中加单引号（例如，"'My Sheet'!A:Z"）
• 查找不支持不带范围的工作表名称；务必指定范围

4. 按键值插入或更新行

适用场景：用户想根据唯一键列更新现有行或插入新行

工具调用顺序：

1. GOOGLESHEETS_UPSERT_ROWS - 更新匹配的行或追加新行 [必需]

关键参数：

• spreadsheetId：目标电子表格 ID
• sheetName：工作表标签名称
• keyColumn：用作唯一标识符的列标题名称（例如，'Email'、'SKU'）
• headers：数据的列名称列表
• rows：数据行的二维数组
• strictMode：列数不匹配时是否报错（默认值为 true）

注意事项：

• keyColumn 必须是实际的标题名称，而不是列字母（例如，'Email'，而不是 'A'）
• 如果未提供 headers，则将 rows 的第一行视为标题
• 当 strictMode=true 时，值的数量多于标题的行会导致错误
• 会自动将缺失的列添加到工作表中

5. 设置单元格格式

适用场景：用户想为单元格应用格式（粗体、颜色、字号）

工具调用顺序：

1. GOOGLESHEETS_GET_SPREADSHEET_INFO - 获取目标工作表标签的数字 sheetId [前置条件]
2. GOOGLESHEETS_FORMAT_CELL - 对某个范围应用格式 [必需]
3. GOOGLESHEETS_UPDATE_SHEET_PROPERTIES - 更改冻结行、列宽 [可选]

关键参数：

• spreadsheet_id：电子表格 ID
• worksheet_id：数字 sheetId（不是工作表标签名称）；通过 GET_SPREADSHEET_INFO 获取
• range：A1 表示法（例如，'A1:F1'）——优先于索引字段
• bold、italic、underline、strikethrough：布尔格式选项
• red、green、blue：背景颜色，取值为 0.0-1.0 的浮点数（不是 0-255 的整数）
• fontSize：字号，单位为点

注意事项：

• 需要数字 worksheet_id，而非工作表标签标题；从电子表格元数据中获取
• 颜色通道取值为 0-1 的浮点数（例如，纯红色为 1.0），而非 0-255 的整数
• 响应可能返回空回复对象（[{}]）；请通过回读验证格式
• 每次调用只能设置一个范围的格式；批量设置格式需要分别调用

常见模式

ID 解析

• 电子表格名称 -> ID：使用带有 query 的 GOOGLESHEETS_SEARCH_SPREADSHEETS
• 工作表标签名称 -> sheetId：使用 GOOGLESHEETS_GET_SPREADSHEET_INFO，从 sheets 元数据中提取
• 检查工作表标签是否存在：GOOGLESHEETS_FIND_WORKSHEET_BY_TITLE

速率限制

Google Sheets 实施严格的速率限制：

• 每分钟最多读取 60 次、写入 60 次
• 超出限制会导致错误；尽可能使用批量操作
• 使用 GOOGLESHEETS_BATCH_GET 和 GOOGLESHEETS_BATCH_UPDATE 提高效率

数据模式

• 写入前务必先读取，以了解现有布局
• 对于 CRM 同步、库存更新和去重场景，使用 GOOGLESHEETS_UPSERT_ROWS
• 追加模式（省略 first_cell_location）是添加新记录最稳妥的方式
• 使用 GOOGLESHEETS_CLEAR_VALUES 清除内容，同时保留格式

已知注意事项

• 工作表标签名称：默认名称因区域设置而异；非英语账户中可能不存在“Sheet1”
• 范围表示法：名称中带空格的工作表在 A1 表示法中需要用单引号括起来
• 无界范围：在大型工作表上可能导致超时；请始终指定行范围（例如，'A1:Z10000'）
• 二维数组：所有值参数都必须是列表的列表，即使只有一行也不例外
• 颜色值：使用 0.0-1.0 之间的浮点数，而不是 0-255 的整数
• 格式设置 ID：FORMAT_CELL 需要数值型 sheetId，而不是工作表标签标题
• 速率限制：每分钟最多读取 60 次、写入 60 次；请批量处理以遵守限制
• 删除维度：GOOGLESHEETS_DELETE_DIMENSION 不可撤销；请仔细检查范围

快速参考

任务	工具别名	关键参数
搜索电子表格	GOOGLESHEETS_SEARCH_SPREADSHEETS	query、search_type
创建电子表格	GOOGLESHEETS_CREATE_GOOGLE_SHEET1	title
列出工作表标签	GOOGLESHEETS_GET_SHEET_NAMES	spreadsheet_id
添加工作表标签	GOOGLESHEETS_ADD_SHEET	spreadsheetId、title
读取数据	GOOGLESHEETS_BATCH_GET	spreadsheet_id、ranges
读取单个范围	GOOGLESHEETS_VALUES_GET	spreadsheet_id、range
写入数据	GOOGLESHEETS_BATCH_UPDATE	spreadsheet_id、sheet_name、values
更新范围	GOOGLESHEETS_VALUES_UPDATE	spreadsheet_id、range、values
追加行	GOOGLESHEETS_SPREADSHEETS_VALUES_APPEND	spreadsheetId、range、values
插入或更新行	GOOGLESHEETS_UPSERT_ROWS	spreadsheetId、sheetName、keyColumn、rows
查找行	GOOGLESHEETS_LOOKUP_SPREADSHEET_ROW	spreadsheet_id、query
设置单元格格式	GOOGLESHEETS_FORMAT_CELL	spreadsheet_id、worksheet_id、range
设置筛选器	GOOGLESHEETS_SET_BASIC_FILTER	spreadsheetId、filter
清除值	GOOGLESHEETS_CLEAR_VALUES	spreadsheet_id、range
删除行/列	GOOGLESHEETS_DELETE_DIMENSION	spreadsheet_id、sheet_name、dimension
电子表格信息	GOOGLESHEETS_GET_SPREADSHEET_INFO	spreadsheet_id
更新工作表标签属性	GOOGLESHEETS_UPDATE_SHEET_PROPERTIES	spreadsheetId、properties

---

由 Composio 提供支持