Google Sheets Mcp

google-sheets-mcp

[CI] [Latest release] [Go Reference] [License: Apache 2.0]

Google Sheets as MCP tools. Read and write ranges without destroying the formulas underneath. One Go binary over stdio, signed in as you, with your own OAuth client and the refresh token in your OS keyring.

It is for a person with a Google account who wants an assistant to read, write and reshape the spreadsheets they can already open, as them. It works inside a spreadsheet: values, formulas, formatting, sheets, charts, pivot tables, Connected Sheets, cell comments and notes. Finding, sharing, moving and trashing files, and their revisions, belong to a server built on the Drive API.

Goals and non-goals

Goals:

• A write never destroys what it did not see. The target is read first. Overwriting anything non-empty, a formula above all, is refused until the call says so, naming the cells, and carries the checkpoint of what it replaces.
• What Google changes is said. Every write reports each value Google stored differently from how it was sent, and every delete names what it takes, including what Google removes without saying so.
• The model never guesses an address. Ranges are A1 throughout, sheet titles are read and quoted, and every read is a grid with its column letters and row numbers.
• Nothing irreversible or outward-reaching runs unless you turn it on. Deletes are not registered by default and need confirm, and a formula that makes Google fetch a URL needs a setting no argument can lift.
• Reads are bounded. Every read has a budget in cells and characters, resolved before the call, and says where to continue.
• Act as you, and log nothing about your spreadsheets. Every call runs as the signed-in account, and the logs never carry cell values, formulas, titles, ranges or search terms.

Non-goals:

• Files, folders, sharing and revisions. Drive is read only to find a spreadsheet by title, show its owner and modified time, and name the signed-in account.
• Spreadsheet settings. No tool changes a spreadsheet's title, locale or recalculation setting.
• Changes pushed to it. The Sheets API has no push channel or change feed.
• Apps Script, add-ons or a calculation engine. Formulas are written and read as text, and Google computes them.
• A hosted service. It speaks stdio only, so Claude on the web and on mobile cannot reach it.
• Asking you before a call. Your client approves each call; the server asks nothing.

What makes this one different

• Guarded writes. 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. write_values reads the target first and refuses to overwrite anything non-empty without overwrite, or a formula without overwrite_formulas as well.
• It does the index arithmetic. Google names the first sheet in the account's language, so it is often not an English word. Titles are read from the spreadsheet and quoted for you, and the model never sees a GridRange.
• Coercion is reported. input: typed parses as a person typing, so 007 becomes 7; every value Google changed comes back named.
• A curated surface, gated by registration. A tool that is switched off is not registered, so it cannot be called at all.
• Verifiable releases. Signed checksums, build provenance, SBOMs and reproducible builds.

Tools

The Scope column names what each tool needs. A spreadsheet named by its title is found through Drive, under drive.readonly. In read-only mode, spreadsheets.readonly takes the place of spreadsheets.

The destructive tools are not registered at all unless GSHEETS_ENABLE_DESTRUCTIVE=true, and each still needs confirm: true on the call. connect_data_source and manage_data_source are not registered unless GSHEETS_ENABLE_DATA_SOURCES=true, which is also what makes login ask for the BigQuery scope. Connected Sheets needs a Cloud project with BigQuery and billing before it does anything, so asking everyone for that scope would be the wrong default.

Resources

For a client that attaches a spreadsheet rather than calling a tool. There is no static list, since listing a person's spreadsheets is a Drive listing, and no subscriptions, since the Sheets API has no push.

Install

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

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

Claude Desktop users can open the .mcpb bundle from the same release. It installs the server and asks for the settings a client's configuration would carry: your OAuth client JSON, the profile, read-only, the destructive switch, Connected Sheets and external formulas. It covers macOS, Windows and Linux on both architectures.

The bundle does not log you in. Install the binary as well and run google-sheets-mcp login as below; the bundle picks up the same credentials. Leave its OAuth client field empty to use the client that login recorded; a file you pick there must be that same client, since the refresh token belongs to it.

Sign in

You bring your own OAuth client. 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.

3. Configure the consent screen: Internal for a Workspace account, External + Testing for a consumer one, which means running login again weekly, because Google expires a testing app's refresh token.

4. On an External app, add the scopes login requests. Google asks for the list only from apps used by people outside your Workspace organization, so an Internal app can skip this step:

   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	Finding spreadsheets, their owner and modified time, and the account's address; never a write

   With GSHEETS_ENABLE_DATA_SOURCES=true, add a third:

   Scope	What it is for
   https://www.googleapis.com/auth/bigquery.readonly	connect_data_source and manage_data_source

   With GSHEETS_READ_ONLY=true, login asks for https://www.googleapis.com/auth/spreadsheets.readonly in place 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, and check it:

google-sheets-mcp login -secret ./client_secret.jsongoogle-sheets-mcp doctor

login prints the authorization URL and tries to open your browser. The callback lands on 127.0.0.1 on a random port, with PKCE and state. 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 says so. Add -enable-data-sources=true to log in for Connected Sheets.

doctor checks the client JSON, the token, the granted scopes and one call to Drive, and names what is missing. status says which account is signed in and where the token lives. status --json prints the same as one object for a script, with the account masked to its domain: credentials.configured is the field to branch on, and schema_version changes only when a field is removed or changes meaning. logout -yes revokes the token at Google and deletes the local copy.

Over SSH, the callback goes to the remote host's loopback address. Read the port from the printed URL, where it appears as 127.0.0.1%3A<port>, forward it from a second local terminal, then open the URL locally:

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

Connect a client

Claude Code:

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

Any client that takes a JSON server list:

{  "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, or open the .mcpb bundle instead.

Configuration

Every setting is a GSHEETS_* environment variable with a flag of the same name. docs/configuration.md lists them all, with profiles for keeping a work and a personal account apart.

Safety

What registers depends on the settings the server starts with:

Your MCP client approves each call; the server does not ask you itself. claude.ai and Codex prompt for the tools marked destructive, which is every write but those that only add: create_spreadsheet, append_rows and connect_data_source. VS Code prompts for every tool that writes. In Claude Code, delete_data_source asks on every call whatever your rules say, since it takes a sheet and unlinks everything built on the source. For the rest, list the calls you want to approve one by one under permissions.ask in your settings, with the name you gave the server in place of google-sheets. For example, the writes that delete, start a billed query, or can email someone:

{  "permissions": {    "ask": [      "mcp__google-sheets__delete_sheet", "mcp__google-sheets__delete_dimensions",      "mcp__google-sheets__clear_values", "mcp__google-sheets__delete_cell_comment",      "mcp__google-sheets__delete_data_source", "mcp__google-sheets__connect_data_source",      "mcp__google-sheets__manage_cell_comment"    ]  }}

A client that runs with nobody watching can make every write its settings register, so leave GSHEETS_ENABLE_DESTRUCTIVE and GSHEETS_ENABLE_DATA_SOURCES off for one.

A write never destroys what it cannot see. Overwriting anything non-empty needs overwrite, and a formula needs overwrite_formulas as well, because a formula and its result look identical in a read. Each refusal names the cells. An overwrite also needs expect_checkpoint, which the refusal and a dry run give, so a collaborator's edit after that read makes the write a [conflict] rather than something replaced unseen. The guard also covers what Google removes without saying so:

• a merge keeps the top-left value of each merged block and discards the rest;
• clear_format removes formatting Sheets cannot bring back;
• a note set or cleared replaces something no values read shows;
• a paste or an auto-fill lands on cells you did not name, so the landing rectangle is read and guarded;
• a text_to_columns spills into the columns to its right;
• a find_replace with in_formulas rewrites what a cell computes;
• deleting a table takes every conditional format rule over its range;
• deleting a row or column takes any anchor on it, which delete_dimensions names first.

Beyond the guard:

• Formulas that reach outside are the operator's call. IMPORTXML, IMPORTDATA, IMPORTHTML, IMPORTFEED, IMAGE and HYPERLINK make Google fetch a URL, and IMPORTRANGE pulls in another spreadsheet. Every write refuses them unless the server was started with GSHEETS_ALLOW_EXTERNAL_FORMULAS=true.
• The gated deletes name what they take, in A1, so the call your client shows says what goes.
• dry_run on every write. Sheets has no suggestion mode, so the preview reports what the guard found and what would change, and sends nothing.
• Sheet names are read, never assumed. Sheet1 does not exist on a Portuguese account, so no tool defaults a sheet, and a missing one is refused with the titles that do exist.

docs/security.md has the threat model.

Verify a release

Each release signs checksums.txt with a keyless Sigstore certificate tied to the release workflow, attests every archive and the bundle, and ships an SBOM per archive. Builds are reproducible: rebuilding a tag gives the same bytes.

sha256sum -c checksums.txt --ignore-missingcosign verify-blob checksums.txt --bundle checksums.txt.bundle \  --certificate-identity "https://github.com/mmedum/google-sheets-mcp/.github/workflows/release.yml@refs/tags/<tag>" \  --certificate-oidc-issuer https://token.actions.githubusercontent.comgh attestation verify <archive> --repo mmedum/google-sheets-mcp

Getting help

Run google-sheets-mcp doctor first: most first-run trouble is an API that was never enabled or a consent screen without you on it. docs/troubleshooting.md covers each failure. Then open an issue with doctor's output and the version. Never paste a spreadsheet id or URL, cell contents, a client JSON, a token or a tool result; describe the shape instead.

Documentation

• docs/gcp-setup.md: the Cloud project, the OAuth client and logging in.
• docs/configuration.md: every setting, profiles, and where state is stored.
• docs/troubleshooting.md: symptoms and their fixes, then rotating the token, revoking access and handling a suspected exposure.
• docs/security.md: the threat model.
• docs/architecture.md: how it works, and the design decisions a contributor should not undo.
• docs/release.md: how a release is cut and checked.
• CHANGELOG.md: what each release changed. The tool names, their arguments and their output fields are the contract, and anything you have to act on is marked Breaking.

Contributing

CONTRIBUTING.md covers the gates, the live run and the review flow. Security reports go through SECURITY.md, not an issue. Participation follows the CODE_OF_CONDUCT.md.

License

Apache 2.0. See LICENSE.