google-sheets-automation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Google Sheets

Lightweight Google Sheets integration with standalone OAuth authentication. No MCP server required. Full read/write access.

Requires Google Workspace account. Personal Gmail accounts are not supported.

轻量级Google Sheets集成工具，自带独立OAuth身份验证，无需MCP服务器，支持完整读写权限。

需要Google Workspace账号，不支持个人Gmail账号。

First-Time Setup

首次设置

Authenticate with Google (opens browser):

bash

python scripts/auth.py login

Check authentication status:

bash

python scripts/auth.py status

Logout when needed:

bash

python scripts/auth.py logout

使用Google账号完成身份验证（将自动打开浏览器）：

bash

python scripts/auth.py login

查看身份验证状态：

bash

python scripts/auth.py status

需要时可退出登录：

bash

python scripts/auth.py logout

Read Commands

读取命令

All operations via

scripts/sheets.py

. Auto-authenticates on first use if not logged in.

bash

undefined

所有操作都通过

scripts/sheets.py

执行，若未登录，首次使用时会自动触发身份验证流程。

bash

undefined

Get spreadsheet content as plain text (default)

将电子表格内容以纯文本形式返回（默认格式）

python scripts/sheets.py get-text SPREADSHEET_ID

Get spreadsheet content as CSV

将电子表格内容以CSV格式返回

python scripts/sheets.py get-text SPREADSHEET_ID --format csv

Get spreadsheet content as JSON

将电子表格内容以JSON格式返回

python scripts/sheets.py get-text SPREADSHEET_ID --format json

Get values from a specific range (A1 notation)

获取指定范围的数值（A1表示法）

python scripts/sheets.py get-range SPREADSHEET_ID "Sheet1!A1:D10" python scripts/sheets.py get-range SPREADSHEET_ID "A1:C5"

Find spreadsheets by search query

通过搜索查询查找电子表格

python scripts/sheets.py find "budget 2024" python scripts/sheets.py find "sales report" --limit 5

Get spreadsheet metadata (sheets, dimensions, etc.)

获取电子表格元数据（工作表、维度等信息）

python scripts/sheets.py get-metadata SPREADSHEET_ID

undefined

python scripts/sheets.py get-metadata SPREADSHEET_ID

undefined

Write Commands

写入命令

bash

undefined

bash

undefined

Update a range of cells with values (JSON 2D array)

用数值更新指定范围的单元格（JSON二维数组格式）

python scripts/sheets.py update-range SPREADSHEET_ID "Sheet1!A1:B2" '[["Hello","World"],["Foo","Bar"]]'

Update with RAW input (no formula parsing, treats everything as literal text)

使用RAW输入（不解析公式，所有内容都按字面文本处理）

python scripts/sheets.py update-range SPREADSHEET_ID "Sheet1!A1:B1" '[["=SUM(A1:A5)","text"]]' --raw

Append rows after the last data row

在最后一行数据之后追加新行

python scripts/sheets.py append-rows SPREADSHEET_ID "Sheet1!A:Z" '[["New Row Col A","New Row Col B"]]'

Clear values from a range (keeps formatting)

清空指定范围的数值（保留原有格式）

python scripts/sheets.py clear-range SPREADSHEET_ID "Sheet1!A1:B10"

Batch update (advanced - for formatting, merging, etc.)

批量更新（高级功能，可用于设置格式、合并单元格等操作）

python scripts/sheets.py batch-update SPREADSHEET_ID '[{"updateCells":{"range":{"sheetId":0},"fields":"userEnteredValue"}}]'

undefined

python scripts/sheets.py batch-update SPREADSHEET_ID '[{"updateCells":{"range":{"sheetId":0},"fields":"userEnteredValue"}}]'

undefined

Spreadsheet ID

电子表格ID

You can use either:

The spreadsheet ID:

1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms

The full URL:

https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/edit

The script automatically extracts the ID from URLs.

你可以任选以下两种形式传入：

电子表格ID：

1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms

完整URL：

https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/edit

脚本会自动从URL中提取ID。

Output Formats

输出格式

Text (default)

文本（默认）

Human-readable format with pipe separators:

Spreadsheet Title: Sales Data
Sheet Name: Q1
Name | Revenue | Units
Product A | 10000 | 50
Product B | 15000 | 75

采用竖线分隔的人类可读格式：

Spreadsheet Title: Sales Data
Sheet Name: Q1
Name | Revenue | Units
Product A | 10000 | 50
Product B | 15000 | 75

CSV

Standard CSV format, suitable for further processing:

Name,Revenue,Units
Product A,10000,50
Product B,15000,75

标准CSV格式，适合后续数据处理：

Name,Revenue,Units
Product A,10000,50
Product B,15000,75

JSON

Structured data format:

json

{
  "Q1": [
    ["Name", "Revenue", "Units"],
    ["Product A", "10000", "50"]
  ]
}

结构化数据格式：

json

{
  "Q1": [
    ["Name", "Revenue", "Units"],
    ["Product A", "10000", "50"]
  ]
}

A1 Notation Examples

A1表示法示例

```
Sheet1!A1:B10
```
- Range A1 to B10 on Sheet1
```
Sheet1!A:A
```
- All of column A on Sheet1
```
Sheet1!1:1
```
- All of row 1 on Sheet1
```
A1:C5
```
- Range on the first sheet

```
Sheet1!A1:B10
```
- Sheet1工作表上A1到B10的范围
```
Sheet1!A:A
```
- Sheet1工作表上整个A列
```
Sheet1!1:1
```
- Sheet1工作表上整个第1行
```
A1:C5
```
- 第一个工作表上A1到C5的范围

Value Input Options

数值输入选项

USER_ENTERED (default): Values are parsed as if typed by a user. Numbers, dates, and formulas are interpreted.
RAW (
```
--raw
```
flag): Values are stored exactly as provided. No parsing of formulas or number formatting.

USER_ENTERED（默认）：数值会按照用户手动输入的规则解析，数字、日期和公式都会被识别处理。
RAW（
```
--raw
```
参数）：数值会完全按照输入内容存储，不会解析公式或进行数字格式化。

Token Management

令牌管理

Tokens stored securely using the system keyring:

macOS: Keychain
Windows: Windows Credential Locker
Linux: Secret Service API (GNOME Keyring, KDE Wallet, etc.)

Service name:

google-sheets-skill-oauth

Tokens automatically refresh when expired using Google's cloud function.

令牌通过系统密钥环安全存储：

macOS：钥匙串（Keychain）
Windows：Windows凭据保险箱（Windows Credential Locker）
Linux：Secret Service API（GNOME密钥环、KDE钱包等）

服务名称：

google-sheets-skill-oauth

令牌过期时会通过Google云函数自动刷新。

When to Use

适用场景

Use this skill when tackling tasks related to its primary domain or functionality as described above.

当你需要处理上述核心功能领域相关的任务时，可以使用这个skill。