sheets-mcp
Full Google Sheets API v4 coverage for AI agents — 14 tools, two auth paths, SQL-powered data engine.
What is sheets-mcp?
sheets-mcp is a hosted MCP server that gives any AI agent — Claude, Cursor, or your own — complete programmatic control over Google Sheets.
It exposes 14 source-verified tools covering the full Sheets API v4 surface without flooding the agent context window. Two lines in your MCP config and your agent can read, write, analyze, and structurally transform spreadsheets.
- Quickstart — Connect your first AI agent in under 5 minutes.
- Authentication — OIDC for Claude Desktop / Cursor. API key for scripts and CI.
- Tools Reference — All 14 tools with full input schemas and safety rules.
- SQL in Sheets — Run Postgres queries against live sheet data — zero context cost.
Why sheets-mcp?
Agent Experience (AX) first
analyze_range and transform_range execute SQL directly against Sheets data in a sandboxed Postgres pool — your agent never pulls raw rows into its context window. The schema is co-delivered with every read_range call at zero extra latency. Tool schemas were trimmed 41% in v1.1.0 to maximize agent reasoning budget.
Fails closed, not open
write_range and transform_range block writes that would silently destroy formula cells or spill into ARRAYFORMULA ranges. Opt in to overrides explicitly with allowFormulaOverwrite: true. Protected Ranges are respected — strict locks cannot be bypassed programmatically.
Two auth paths
OIDC (OAuth2 + JWT) for interactive clients like Claude Desktop and Cursor — full browser-based consent flow. API key (x-api-key header) for headless scripts, CI pipelines, and custom agents. Both paths resolve to the same Google OAuth session internally.
Full undo support
Every write_range and transform_range call saves a pre-write snapshot to write_history. restore_snapshot can list and restore up to 50 snapshots per spreadsheet — no manual backups needed.
Tool surface
| Category | Tools |
|---|---|
| Read | list_spreadsheets, list_sheets, read_range |
| Write | write_range, append_rows, clear_range, format_cells |
| SQL | analyze_range, transform_range |
| Manage | create_spreadsheet, manage_sheets, copy_sheet, batch_update_sheet, restore_snapshot |
| Drive | manage_drive |
Stack
Next.js 16 on Vercel · better-auth (OIDC provider + API key plugin) · Supabase Postgres (sessions, schema cache, write history) · googleapis JS SDK with proactive token refresh · OpenTelemetry (stdout trace exporter for agent log visibility) · Zod v4 schemas · Framer Motion UI