google-sheets-mcp

MCP server to read and edit Google Sheets. Built for editorial calendars, task trackers and any agency-style spreadsheet workflow.

Tools (22)

Tool	What it does
get_spreadsheet_info	Title, tabs and dimensions of the spreadsheet
get_sheet_data	All data of a tab as an array of rows
read_range	Read a specific A1 range
read_multiple_ranges	Read several ranges in a single API call — more efficient than calling read_range repeatedly
write_range	Write data into a range (overwrites)
update_cell	Update a single cell
batch_update_cells	Update multiple individual cells in a single API call
append_rows	Append rows at the end of a tab
find_replace	Find and replace text across the whole spreadsheet
clear_range	Clear a range
insert_rows	Insert N blank rows starting at a given row
delete_rows	Delete a range of rows
add_sheet	Create a new tab
rename_sheet	Rename a tab
copy_sheet	Duplicate a tab within the same spreadsheet
format_range	Apply formatting (background color, bold, font size, alignment)
freeze_rows	Freeze the top N rows
create_spreadsheet	Create a new empty spreadsheet
get_hyperlinks	Extract hyperlink URLs from cells in a range — useful when a cell displays text that links elsewhere
sort_range	Sort a range by a column (ascending or descending)
auto_resize_columns	Auto-fit column widths to content
duplicate_spreadsheet	Clone an entire spreadsheet (all tabs and data)

Semantic colors for format_range

Name	Use
hecho	Light green — task done
in_progress	Light yellow — in progress
por_hacer	Light grey — pending
alta	Light red — high priority
media	Light yellow — medium priority
baja	Light blue — low priority
header	Steel blue — table header
white, red, green, blue, yellow, orange, purple, grey	Basic colors
#RRGGBB	Direct hex

Setup

1. Create a Google Cloud project (or reuse one) and enable the Google Sheets API, Google Docs API and Google Drive API (the token scopes cover all three, so you can reuse it with the sibling google-docs-mcp server if you want).
2. Create an OAuth 2.0 Client ID of type "Desktop app" and download it as client_secret.json.
3. If the app is in "Testing" mode, add your Google account as a test user.
4. Install dependencies:

   python3 -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt
   

5. Run the OAuth flow once:

   CLIENT_SECRET_PATH=~/.config/google-sheets-mcp/client_secret.json \
     python3 setup_auth.py
   

   This opens a browser — log in and grant access.

MCP client configuration

{
  "mcpServers": {
    "google-sheets": {
      "command": "/path/to/.venv/bin/python3",
      "args": ["/path/to/google-sheets-mcp/server.py"],
      "env": {
        "GOOGLE_WORKSPACE_TOKEN_PATH": "~/.config/google-workspace-mcp/token.json"
      }
    }
  }
}

Env var	Default	Purpose
GOOGLE_WORKSPACE_TOKEN_PATH	~/.config/google-workspace-mcp/token.json	Path to the OAuth token

Suggested task-sheet structure

Standard columns (row 1 = header): OWNER | START | END | TASK | TOPIC | STATUS | PRIORITY | DETAILS

Suggested status values: TODO, IN PROGRESS, DONE Suggested priorities: HIGH, MEDIUM, LOW

License

MIT — see LICENSE.