google-sheets-mcp

# google-sheets-mcp

[![CI](https://github.com/mmedum/google-sheets-mcp/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/mmedum/google-sheets-mcp/actions/workflows/ci.yml)
[![Latest release](https://img.shields.io/github/v/release/mmedum/google-sheets-mcp?sort=semver)](https://github.com/mmedum/google-sheets-mcp/releases/latest)
[![Go Reference](https://pkg.go.dev/badge/github.com/mmedum/google-sheets-mcp.svg)](https://pkg.go.dev/github.com/mmedum/google-sheets-mcp)
[![License: Apache 2.0](https://img.shields.io/github/license/mmedum/google-sheets-mcp)](./LICENSE)

Google Sheets as MCP tools. Read and write ranges without destroying the formulas underneath.

A single Go binary that speaks MCP over stdio. It runs as a subprocess of
your client, on your own machine, against your own Google account. There
is no server to host, no shared deployment and no service account: you
create a Google OAuth client, log in once, and the refresh token stays in
your OS keyring.

It works **inside** a spreadsheet. Finding, sharing, moving and trashing
files, and their comment threads and revisions, belong to a server built
on the Drive API. A cell **note** is a Sheets field and is here.

## Why google-sheets-mcp

A spreadsheet has no undo behind an API call, and the value you can see
is rarely the whole cell: underneath it there may be a formula, a
different stored type, or a note. So the writes here are guarded rather
than trusting. `write_values` reads the target first and refuses to
overwrite anything non-empty without `overwrite`, or a formula without
`overwrite_formulas` as well, naming the cells each time; every value
Google's parser changes on the way in is reported back to you.

It also does the index arithmetic. Ranges are A1 throughout, sheet titles
are quoted for you — Google names the first sheet in the account's
language, so it is often not an English word — and the one place A1 turns
into a `GridRange` is a single package.

It works **inside** a spreadsheet. Finding, sharing, moving and trashing
files, and their comment threads and revisions, belong to a server built
on the Drive API. A cell **note** is a Sheets field and is here.

Reading, writing, formatting, the objects attached to a range,
`gsheets://` resources, durable anchors, charts, pivot tables and
Connected Sheets data sources all work. The twenty-one tools and their
arguments are stable: a breaking change needs a major version, and a gate
compares every commit against the last tag. It has been driven by one MCP
client, which is what to know before trusting it in a second. The history
is §16 of [`docs/architecture.md`](docs/architecture.md).

## Install

```bash
go install github.com/mmedum/google-sheets-mcp/cmd/google-sheets-mcp@latest
```

Or take an archive from the
[latest release](https://github.com/mmedum/google-sheets-mcp/releases/latest)
— Linux, macOS and Windows, on amd64 and arm64 — and verify it before you
run it:

```bash
sha256sum -c checksums.txt --ignore-missing

# The checksum file is signed with a keyless Sigstore certificate tied to
# the release workflow's identity. The bundle carries both.
cosign verify-blob checksums.txt \
  --bundle checksums.txt.bundle \
  --certificate-identity-regexp 'https://github\.com/mmedum/google-sheets-mcp/' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

# And the archive itself carries build provenance.
gh attestation verify google-sheets-mcp_*.tar.gz --repo mmedum/google-sheets-mcp
```

Every archive also ships an SBOM, so you can see what is inside a binary
you did not build. Builds are reproducible: `-trimpath`, and the commit's
timestamp rather than the build's, so rebuilding a tag gives the same
bytes.

### Claude Desktop

Every release also carries a `.mcpb` bundle. Open it and Claude Desktop
installs the server and asks for your OAuth client JSON — no config file
to edit. It covers macOS, Windows and Linux on both architectures each:
macOS through a universal binary, Windows through amd64, and Linux
through a small launcher that picks the right binary at start, because a
bundle manifest has no key for the architecture. Its SHA-256 is in the
same signed `checksums.txt`.

The bundle does **not** log you in. Install the binary as well, run
`google-sheets-mcp login -secret <your client JSON>` once, and the bundle
picks up the same credentials. Claude Code does not install `.mcpb`
files, so it uses the command below.

## Set up Google

You need your own OAuth client. It takes about fifteen minutes once, and
[`docs/gcp-setup.md`](docs/gcp-setup.md) walks through it with the
reasons. In short, and in the order `doctor` checks things in:

1. Create a Google Cloud project.
2. Enable the **Google Sheets API**, and the **Google Drive API** — the
   second for `search_spreadsheets`, which is the only Drive call this
   server makes.
3. Configure the consent screen: **Internal** for a Workspace account,
   **External + Testing** for a consumer one — which means re-running
   `login` weekly, because Google expires a testing app's refresh token.
4. Add these two scopes, which are exactly what `login` requests:

   | Scope | What it is for |
   |---|---|
   | `https://www.googleapis.com/auth/spreadsheets` | Everything this server does inside a spreadsheet |
   | `https://www.googleapis.com/auth/drive.readonly` | `search_spreadsheets`, and nothing else |

   And a third, **only** if you want Connected Sheets:

   | Scope | What it is for |
   |---|---|
   | `https://www.googleapis.com/auth/bigquery.readonly` | `manage_data_source`, and only with `GSHEETS_ENABLE_DATA_SOURCES=true` |

   `login` asks for it only when that setting is on, so leaving it off
   means the consent screen is exactly the two scopes above. Google
   refuses `addDataSource` without it — "Please include bigquery.readonly
   scope" — so there is no half-working middle state to be surprised by.

   `drive.readonly` rather than `drive` or `drive.file` on purpose: this
   server finds spreadsheets and never creates, moves or trashes a file,
   and the narrower scope is what makes that a guarantee rather than a
   promise. It is also why the live driver cannot clean up after itself.

   With `GSHEETS_READ_ONLY=true`, `login` asks for
   `https://www.googleapis.com/auth/spreadsheets.readonly` instead of the
   first, and the write tools are not registered at all.
5. Create an **OAuth 2.0 Client ID** of type **Desktop app** and download
   the JSON.

Then log in:

```bash
google-sheets-mcp login -secret ./client_secret.json
```

Login prints the authorization URL and then tries to open your browser;
if it cannot, the URL is already on screen. The callback lands on
`127.0.0.1` on a random port, with PKCE and state throughout. The refresh
token goes into your OS keyring; if there is no keyring it goes into a
`0600` file under your config directory and the command tells you so.

`google-sheets-mcp status` says which account is signed in and where the
token lives. `google-sheets-mcp logout` revokes the token at Google and
deletes the local copy. `google-sheets-mcp doctor` checks the
credentials, the granted scopes and what Google actually answers, and
names what is missing — it masks the client id and the account, so its
output is safe to paste into an issue.

`google-sheets-mcp status --json` prints the same state as one JSON
object on stdout, for a script that needs to know whether this server is
configured before starting it. `credentials.configured` is the field to
branch on, `schema_version` changes only when a field is removed or its
meaning changes, and the account is masked to its domain exactly as the
text output masks it. A label in the human output is free to be reworded
in any release; the object is not.

### Logging in over SSH

The callback goes to the *remote* host's loopback address and your
browser is local, so forward the port. It is chosen at random and printed
only once login is already waiting, so read it out of the printed URL —
it appears percent-encoded, as `127.0.0.1%3A<port>` — and in a second
local terminal:

```bash
ssh -N -L <port>:127.0.0.1:<port> user@remote-host
```

Then open the URL locally.

## Connect a client

Claude Code:

```bash
claude mcp add google-sheets -- google-sheets-mcp
```

Or, in a client config file:

```json
{
  "mcpServers": {
    "google-sheets": {
      "command": "google-sheets-mcp"
    }
  }
}
```

Claude Desktop reads the same shape from its own config file. Use the
binary's absolute path there if it is not on the app's `PATH`.

Every setting is a `GSHEETS_*` environment variable with a flag of the
same name, listed in [`docs/configuration.md`](docs/configuration.md).
The three worth knowing now: `GSHEETS_READ_ONLY=true` requests read-only
scopes and registers only the read tools,
`GSHEETS_ENABLE_DESTRUCTIVE=true` registers the three tools that remove
things, and `GSHEETS_PROFILE` lets one machine hold a work account and a
personal one.

## Tools

Seventeen tools. Everything but `search_spreadsheets` needs only the
Sheets scope; in read-only mode the read tools ask for
`spreadsheets.readonly` instead.

| Tool | What it does | Scope |
|---|---|---|
| `get_spreadsheet` | The spreadsheet card: title, link, locale, and every sheet's exact title, id, size, frozen rows, hidden state and what it holds, plus named ranges, tables, protected ranges and filter views. No cell data, so it costs the same on a spreadsheet of ten cells and one of ten million. Call it first | `spreadsheets` |
| `read_range` | An addressed grid of a range: column letters across the top, row numbers down the side. `show=both` prints each formula under the value it produced. Budgeted in cells and characters, with a continuation, and every read returns a checkpoint | `spreadsheets` |
| `read_formatting` | What a range looks like — number formats, fonts, colours, borders, alignment — per block of identically formatted cells rather than per cell, with the merges, conditional rules, banding