google-sheets-mcp

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.

Install

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

Or take an archive from the latest release — Linux, macOS and Windows, on amd64 and arm64 — and verify it before you run it:

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 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:

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:

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

Then open the URL locally.

Connect a client

Claude Code:

claude mcp add google-sheets -- google-sheets-mcp

Or, in a client config file:

{
  "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. 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.