Google Sheets MCP Plugin v2.0.0

A Claude plugin that gives Claude full read, write, format, and structural control over Google Sheets — no browser automation needed. 43 tools across data, formatting (whole-cell AND inline rich text), structure, charts, filters, pivot tables, data validation, and more.

Sheets-only OAuth scope. This plugin only requests https://www.googleapis.com/auth/spreadsheets — read/write access to spreadsheets you open. It does NOT request Drive scope, so it cannot list, browse, or touch any other Drive file.

What's included

43 MCP tools across seven categories.

Data tools

Tool	Purpose
read_range	Read values from a range (e.g. Sheet1!A1:C10)
update_range	Write a 2D array to a range
update_cell	Write a single value to a single cell
append_rows	Append rows to the end of a sheet
batch_update	Apply many range writes atomically
batch_get_ranges	Read multiple ranges in one call
get_sheet_info	List tabs + dimensions for a spreadsheet
get_cell_formula	Get the underlying formula in a cell (not just value)
find_and_replace	Find/replace across a range or whole spreadsheet
fill_down	Auto-fill a formula or value down a column
remove_duplicates	Remove duplicate rows from a range
split_text_to_columns	Split delimited text into multiple columns
clear_range	Clear cell contents (or contents + formatting) in a range
create_spreadsheet	Create a brand-new spreadsheet with optional initial tabs

Formatting tools

Tool	Purpose
format_ranges	Bold, italic, font/bg colors, borders, number formats, alignment, wrap (whole-cell)
format_text_in_cell	Inline character-range formatting — bold/underline/color SPECIFIC words within a cell
conditional_format	Color scales, threshold-based highlighting, custom formula rules
merge_cells	Merge or unmerge cell ranges
add_cell_note	Add a hover-on-cell note (the small triangle indicator)
insert_hyperlink	Insert a clickable hyperlink in a cell
add_image_to_cell	Embed an image inside a cell

format_text_in_cell example — bold "$391K" and underline "+165%" inside a longer paragraph:

format_text_in_cell(
    spreadsheet_id, sheet_id, "B7",
    formats=[
        {"text": "$391K", "bold": True},
        {"text": "+165%", "bold": True, "underline": True},
    ],
)

Structure tools

Tool	Purpose
manage_sheets	Create, delete, rename, or duplicate tabs
insert_delete_dimensions	Insert or delete rows and columns
sort_range	Sort a range by one or more columns
auto_resize_columns	Auto-fit column widths to content
set_column_width	Set explicit column width(s) in pixels
set_row_height	Set explicit row height(s) in pixels
freeze_rows_cols	Freeze top rows and/or left columns
hide_unhide_dimensions	Hide or unhide rows/columns
group_rows_or_columns	Create collapsible row/column groups
set_data_validation	Dropdowns, number constraints, custom formulas
add_dropdown_list	Convenience: attach a dropdown of choices to a range
protect_range	Lock a range against editing (with editor list)
copy_tab_to_spreadsheet	Copy a tab into another spreadsheet

Charts & analysis

Tool	Purpose
create_chart	Create a line/bar/column/pie/area/scatter/combo chart
update_chart	Update an existing chart's range, title, or type
delete_chart	Delete an embedded chart by ID
create_pivot_table	Generate a pivot table from a source range

Filters

Tool	Purpose
apply_filter	Apply a basic filter to a range
clear_filter	Remove the current basic filter
create_filter_view	Save a named filter view

Utilities

Tool	Purpose
find_cells_with_errors	Scan a range and return any #REF!, #N/A, etc.
export_range_as_csv	Return a range as CSV-formatted string

All value writes use valueInputOption=USER_ENTERED, so typed strings that look like numbers/formulas are interpreted the way they would be if you typed them in the UI. Formatting and structure tools use the Sheets batchUpdate API for full control.

Note on sheet_id: Many tools require a numeric sheet_id (tab ID), not a tab name. Call get_sheet_info first to get the sheetId for each tab, then pass that number.

Why this exists

The default Google Sheets connector only supports reading and writing cell values. This plugin adds everything else — formatting, borders, conditional formatting, data validation, tab management, sorting, charts, pivot tables, filters, structural edits, and more. It turns Claude from "can edit spreadsheet data" into "can build and style a professional spreadsheet from scratch."

What this plugin does NOT do

The following were intentionally skipped because they require the much broader Google Drive scope:

• Cell comments (the threaded discussion kind) — use the Sheets UI: right-click → Comment.
• PDF export — use the Sheets UI: File → Download → PDF.

add_cell_note (the simple hover indicator) is included since it goes through the Sheets API directly and doesn't require Drive scope.

Setup

1. Install Python dependencies

pip3 install -r server/requirements.txt --break-system-packages

2. Create a Google Cloud OAuth client

See SETUP_RUNBOOK.md for a detailed walk-through. Short version:

1. Go to Google Cloud Console and create a project (or pick one you already have).
2. Enable the Google Sheets API: APIs & Services → Library → search "Google Sheets API" → Enable.
3. Configure the OAuth consent screen (User Type = External; add your email as a test user).
4. Create credentials: APIs & Services → Credentials → Create Credentials → OAuth client ID → Desktop app.
5. Download the JSON file.

3. Place the credentials file

mkdir -p ~/.config/google-sheets-mcp
mv ~/Downloads/client_secret_*.json ~/.config/google-sheets-mcp/credentials.json

4. Install the plugin

Drop the .plugin file into your Claude plugin install dialog (or zip the plugin folder and import).

5. First-time auth

The first time Claude calls one of the tools, your browser opens for an OAuth consent prompt:

1. Sign in with the Google account that owns the Sheets you want to access.
2. You'll see "Google hasn't verified this app" — click Advanced → Continue. Expected for a personal OAuth app.
3. Grant the Sheets scope.
4. Browser will say "The authentication flow has completed." Close the tab.

Your refresh token is cached at ~/.config/google-sheets-mcp/token.json. You won't see the consent screen again unless you delete the token or revoke the grant.

Usage

Once installed and authenticated, just ask Claude things like:

• "Read A1:F20 from my budget sheet"
• "Update cell B12 with this note: …"
• "Make a chart of column B vs C on the summary tab"
• "Create a new tab called 'May Review' and copy the template into it"
• "Add a dropdown in column C with options: Approved, Pending, Rejected"
• "Bold the header row, freeze it, and auto-fit column widths"

Claude picks the right tool. The Sheet ID is the part of the URL between /spreadsheets/d/ and /edit.

Configuration

Env var	Default	Purpose
SHEETS_MCP_CONFIG_DIR	~/.config/google-sheets-mcp	Directory holding credentials.json + token.json

Security

• OAuth scope is spreadsheets only — no Drive, Docs, or other Workspace access. The plugin literally cannot list or browse your Drive.
• The OAuth client is yours (created in your GCP project). Credentials never leave your machine.
• The token cached at ~/.config/google-sheets-mcp/token.json is the only thing that grants access. To revoke: delete the file and remove the grant at https://myaccount.google.com/permissions.

Troubleshooting

"Google OAuth client credentials not found" — ~/.config/google-sheets-mcp/credentials.json is missing. Re-do setup step 3.

"This app isn't verified" during consent — Expected for a personal OAuth app. Click Advanced → Continue.

"Sheets API error: 403 PERMISSION_DENIED" — You're authenticated but don't have access to that specific Sheet. Open it in your browser; if it's not yours, ask the owner to share it with the Google account you authed with.

Token expired and refresh failed — Delete ~/.config/google-sheets-mcp/token.json and trigger a tool call again to redo the consent flow.

Changelog

• v2.0.0 (2026-05-22) — Major expansion. Added 29 new tools beyond v1.0: inline rich text (format_text_in_cell), explicit dimension sizing (set_column_width, set_row_height), freeze, hide/unhide, group rows/columns, protect range, copy tab, find and replace, fill down, dedupe, split text to columns, dropdowns, filters and filter views, charts (create_chart, update_chart, delete_chart), pivot tables, hyperlinks, images in cells, cell notes, find cells with errors, export range as CSV, create_spreadsheet, clear_range, batch_get_ranges, get_cell_formula. Stripped Drive scope (was never used). Total: 43 tools.
• v1.0.0 (2026-05-07) — Initial release with 14 tools covering core read/write, formatting, conditional formatting, data validation, tab management, sorting, and structural edits.

License

MIT — see LICENSE.

Author

Stephen Pierson — sapierso@gmail.com