Claude Skill

google-sheets

Read and write Google Sheets spreadsheets - get content, update cells, append rows, fetch specific ranges, search for spreadsheets, and view metadata. Use when user asks to: read a spreadsheet, update cells, add data to Google Sheets, find a spreadsheet, check sheet contents, exp

LLM Mart · 0 points · 2 views 0 listing impressions 0 install-command copies
Download sanjay3290-ai-skills-skills_google-sheets-c842558.zip · 10 KB

Install

skills CLI npx skills add https://github.com/sanjay3290/ai-skills/tree/main/skills/google-sheets
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install sanjay3290-ai-skills@llmmart
Git git clone https://github.com/sanjay3290/ai-skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole sanjay3290/ai-skills collection as a plugin from our marketplace. Git is the plain clone.

README

Google Sheets Skill

An AI agent skill for reading Google Sheets spreadsheets - get content, fetch specific ranges, search, and view metadata. Works with Claude Code, Gemini CLI, Cursor, OpenAI Codex, Goose, and other AI clients supporting the Agent Skills Standard.

Features

  • Read Spreadsheets - Get all content as text, CSV, or JSON
  • Get Ranges - Fetch specific cell ranges (A1 notation)
  • Search - Find spreadsheets by name
  • Metadata - View sheet names, dimensions, and properties

Read-only access. Lightweight alternative to the full Google Workspace MCP server.

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

Quick Start

1. Install dependencies

pip install keyring

2. Authenticate

python scripts/auth.py login

This opens a browser for Google OAuth. Tokens are stored securely in your system keyring.

3. Test connection

python scripts/auth.py status

Usage Examples

# Get spreadsheet content as plain text (default)
python scripts/sheets.py get-text SPREADSHEET_ID

# Get spreadsheet content as CSV
python scripts/sheets.py get-text SPREADSHEET_ID --format csv

# Get spreadsheet content as JSON
python scripts/sheets.py get-text SPREADSHEET_ID --format json

# Get values from a specific range (A1 notation)
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

Command Reference

Command Description Arguments
get-text <id> Get all content spreadsheet ID, --format
get-range <id> <range> Get specific cells spreadsheet ID, A1 range
find <query> Search spreadsheets search query, --limit
get-metadata <id> Get sheet info spreadsheet ID

Output Formats

Text (default)

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

CSV

Name,Revenue,Units
Product A,10000,50

JSON

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

A1 Notation Examples

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

Token Management

Tokens stored securely using the system keyring:

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

Service name: google-sheets-skill-oauth

Troubleshooting

"Failed to get access token"

Run python scripts/auth.py login to authenticate.

"Spreadsheet not found"

Check the spreadsheet ID and your access permissions.

"Invalid range"

Verify the A1 notation format and that the sheet name exists.

License

Apache 2.0

Skill manifest

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.

First-Time Setup

Authenticate with Google (opens browser):

python scripts/auth.py login

Check authentication status:

python scripts/auth.py status

Logout when needed:

python scripts/auth.py logout

Read Commands

All operations via scripts/sheets.py. Auto-authenticates on first use if not logged in.

# Get spreadsheet content as plain text (default)
python scripts/sheets.py get-text SPREADSHEET_ID

# Get spreadsheet content as CSV
python scripts/sheets.py get-text SPREADSHEET_ID --format csv

# Get spreadsheet content as JSON
python scripts/sheets.py get-text SPREADSHEET_ID --format json

# Get values from a specific range (A1 notation)
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

Write Commands

# Update a range of cells with values (JSON 2D array)
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)
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"}}]'

Spreadsheet 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.

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

CSV

Standard CSV format, suitable for further processing:

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

JSON

Structured data format:

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

A1 Notation Examples

  • 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

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.

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.

Files (ai-skills)
  • scripts
    • auth.py 12.2 KB
      Loading…
    • requirements.txt 16 B
      Loading…
    • sheets.py 15.1 KB
      Loading…
  • README.md 3.1 KB
    # Google Sheets Skill
    
    An AI agent skill for reading Google Sheets spreadsheets - get content, fetch specific ranges, search, and view metadata. Works with Claude Code, Gemini CLI, Cursor, OpenAI Codex, Goose, and other AI clients supporting the [Agent Skills Standard](https://agentskills.io).
    
    ## Features
    
    - **Read Spreadsheets** - Get all content as text, CSV, or JSON
    - **Get Ranges** - Fetch specific cell ranges (A1 notation)
    - **Search** - Find spreadsheets by name
    - **Metadata** - View sheet names, dimensions, and properties
    
    Read-only access. Lightweight alternative to the full [Google Workspace MCP server](https://github.com/gemini-cli-extensions/workspace).
    
    > **⚠️ Requires Google Workspace account.** Personal Gmail accounts are not supported.
    
    ## Quick Start
    
    ### 1. Install dependencies
    
    ```bash
    pip install keyring
    ```
    
    ### 2. Authenticate
    
    ```bash
    python scripts/auth.py login
    ```
    
    This opens a browser for Google OAuth. Tokens are stored securely in your system keyring.
    
    ### 3. Test connection
    
    ```bash
    python scripts/auth.py status
    ```
    
    ## Usage Examples
    
    ```bash
    # Get spreadsheet content as plain text (default)
    python scripts/sheets.py get-text SPREADSHEET_ID
    
    # Get spreadsheet content as CSV
    python scripts/sheets.py get-text SPREADSHEET_ID --format csv
    
    # Get spreadsheet content as JSON
    python scripts/sheets.py get-text SPREADSHEET_ID --format json
    
    # Get values from a specific range (A1 notation)
    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
    ```
    
    ## Command Reference
    
    | Command | Description | Arguments |
    |---------|-------------|-----------|
    | `get-text <id>` | Get all content | spreadsheet ID, `--format` |
    | `get-range <id> <range>` | Get specific cells | spreadsheet ID, A1 range |
    | `find <query>` | Search spreadsheets | search query, `--limit` |
    | `get-metadata <id>` | Get sheet info | spreadsheet ID |
    
    ## Output Formats
    
    ### Text (default)
    ```
    Spreadsheet Title: Sales Data
    Sheet Name: Q1
    Name | Revenue | Units
    Product A | 10000 | 50
    ```
    
    ### CSV
    ```
    Name,Revenue,Units
    Product A,10000,50
    ```
    
    ### JSON
    ```json
    {"Q1": [["Name", "Revenue", "Units"], ["Product A", "10000", "50"]]}
    ```
    
    ## A1 Notation Examples
    
    - `Sheet1!A1:B10` - Range A1 to B10 on Sheet1
    - `Sheet1!A:A` - All of column A
    - `Sheet1!1:1` - All of row 1
    - `A1:C5` - Range on first sheet
    
    ## Token Management
    
    Tokens stored securely using the system keyring:
    - **macOS**: Keychain
    - **Windows**: Windows Credential Locker
    - **Linux**: Secret Service API (GNOME Keyring, KDE Wallet)
    
    Service name: `google-sheets-skill-oauth`
    
    ## Troubleshooting
    
    ### "Failed to get access token"
    Run `python scripts/auth.py login` to authenticate.
    
    ### "Spreadsheet not found"
    Check the spreadsheet ID and your access permissions.
    
    ### "Invalid range"
    Verify the A1 notation format and that the sheet name exists.
    
    ## License
    
    Apache 2.0
    
  • requirements.txt 16 B
    Loading…
  • SKILL.md 4 KB
    ---
    name: google-sheets
    description: |
      Read and write Google Sheets spreadsheets - get content, update cells, append rows, fetch specific ranges,
      search for spreadsheets, and view metadata. Use when user asks to: read a spreadsheet, update cells,
      add data to Google Sheets, find a spreadsheet, check sheet contents, export spreadsheet data, or get cell values.
      Lightweight integration with standalone OAuth authentication supporting full read/write access.
    license: Apache-2.0
    metadata:
      author: sanjay3290
      version: "1.0"
    ---
    
    # 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.
    
    ## 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
    ```
    
    ## Read Commands
    
    All operations via `scripts/sheets.py`. Auto-authenticates on first use if not logged in.
    
    ```bash
    # Get spreadsheet content as plain text (default)
    python scripts/sheets.py get-text SPREADSHEET_ID
    
    # Get spreadsheet content as CSV
    python scripts/sheets.py get-text SPREADSHEET_ID --format csv
    
    # Get spreadsheet content as JSON
    python scripts/sheets.py get-text SPREADSHEET_ID --format json
    
    # Get values from a specific range (A1 notation)
    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
    ```
    
    ## Write Commands
    
    ```bash
    # Update a range of cells with values (JSON 2D array)
    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)
    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"}}]'
    ```
    
    ## Spreadsheet 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.
    
    ## 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
    ```
    
    ### CSV
    Standard CSV format, suitable for further processing:
    ```
    Name,Revenue,Units
    Product A,10000,50
    Product B,15000,75
    ```
    
    ### JSON
    Structured data format:
    ```json
    {
      "Q1": [
        ["Name", "Revenue", "Units"],
        ["Product A", "10000", "50"]
      ]
    }
    ```
    
    ## A1 Notation Examples
    
    - `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
    
    ## 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.
    
    ## 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.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.