# Google Sheets MCP Server

A small, self-hosted [MCP](https://modelcontextprotocol.io) server that lets Claude read, write, and format Google Sheets directly — no copy-pasting data back and forth between chat and spreadsheet.

## What it does

Five tools, once connected as a Custom Connector in Claude:

- `list_sheet_tabs` — see what tabs exist in a spreadsheet
- `read_range` — read a cell range
- `write_range` — overwrite a cell range
- `append_rows` — add rows without touching what's already there
- `batch_format` — bold, colors, frozen rows, column widths, via raw Sheets API formatting requests

## How it's built

Next.js app on [Vercel](https://vercel.com) (free Hobby tier, no credit card), using the official [`mcp-handler`](https://www.npmjs.com/package/mcp-handler) package for the MCP transport, and the `googleapis` client for Sheets access. A single shared secret (sent as a Bearer token) gates access to the endpoint. Built to be simple enough to self-host in an afternoon, not a service you sign up for.

Each request builds a fresh handler instance instead of reusing one across calls — deliberate, not an oversight, see [Security](#security).

## This is single-tenant, on purpose

One deployment = one Google account = one Claude connector. There's no login screen, no multi-user database, no admin panel. If more than one person wants to use this independently, each person clones this repo and deploys their own copy — takes about 20 minutes with the setup guide below, and keeps everyone's data in their own Google account.

A "real" multi-tenant version (one server, many users, each logging in with their own Google account) is possible but is a genuinely different, bigger project — a proper OAuth broker with a database behind it, not a weekend clone. Wasn't the goal here.

## Setup

See [SETUP.md](./SETUP.md) for the full walkthrough — no prior Google Cloud or MCP experience assumed, about 15–20 minutes start to finish.

## Security

- **Minimal scope.** Only `https://www.googleapis.com/auth/spreadsheets` — read/write to Sheets, nothing else. Not Drive, not Gmail, not your whole Google account.
- **Two supported auth methods** — a personal OAuth login, or a service account for setups that should never need re-authorizing. Pick whichever fits in SETUP.md.
- **Shared-secret auth**, compared with a timing-safe check, not a plain `===`.
- **Use a dedicated Google account** if you can, rather than your main one, and only share the specific sheets you actually want this server to touch.
- **Rotate the secret** if you ever suspect it leaked — generating a new one and redeploying takes a minute.
- **Publish your Google app** (see SETUP.md) — apps left in "Testing" status have their refresh tokens silently expire after 7 days. Not optional if you want this to keep working past a week.
- Errors from the Google API are caught and returned as plain text, not raw stack traces.

This is a personal tool you host and control yourself — there's no third party, including whoever wrote this, that ever sees your Google credentials or your sheet data.

## License

MIT — see [LICENSE](./LICENSE).