Google Sheets Mcp

io.github.mmedumPublished by GitHub account mmedumv4.2.1Updated Nov 4, 2026

Google Sheets as MCP tools: read ranges, write without destroying formulas, format and validate.

VerifiedSTDIODesktop onlyDatabasesProductivity & WorkflowData & Analytics

Overview

AI-generated overview

Local MCP server that lets an assistant read, write, format and restructure Google Sheets as your own signed-in Google account.

What you can do
  • Inspect a spreadsheet's card: sheets, named ranges, tables, protected ranges and filter views
  • Read addressed ranges as grids, with formulas, formatting, merges and validation, and search within a spreadsheet
  • Create spreadsheets and write or append values, with guarded overwrites and reported type coercion
  • Format cells and manage named ranges, protection, validation, banding, tables and conditional rules
  • Sort, trim, de-duplicate, split, fill, copy or move ranges, and anchor rows or columns that survive edits
  • Manage sheets, rows and columns, charts, pivot tables and cell comments; optionally connect BigQuery via Connected Sheets
When to use it
Useful when you want an assistant to work inside spreadsheets you can already open — reading data, filling in values, cleaning up ranges, building charts or pivots, or leaving cell comments — without leaving your client. It is not for finding, sharing, moving or trashing files, which belongs to a Drive-based server.
Requirements
A local Go binary (or the Claude Desktop bundle plus the binary for login) on macOS, Windows or Linux, stdio only. You supply your own Google Cloud OAuth client JSON, with the Sheets and Drive APIs enabled and the required scopes added; sign-in stores a refresh token in the OS keyring. Settings are GSHEETS_* environment variables. Connected Sheets needs a Cloud project with BigQuery and billing.
Before you install
It acts as your Google account with write access to your spreadsheets; writes can overwrite values and formulas, and merges, clears, notes, pastes and deletes remove things silently, so use dry_run and the checkpoint guard. Destructive tools stay unregistered unless GSHEETS_ENABLE_DESTRUCTIVE=true and still need confirm. Connected Sheets tools need GSHEETS_ENABLE_DATA_SOURCES=true and run BigQuery queries billed to your project. External formulas need GSHEETS_ALLOW_EXTERNAL_FORMULAS=true…

Installation

In SourceWeft

  1. Open Google Sheets Mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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.

ToolWhat it doesScope
get_spreadsheetThe 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 firstspreadsheets
read_rangeAn 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 checkpointspreadsheets
read_formattingWhat a range looks like — number formats, fonts, colors, borders, alignment — per block of identically formatted cells rather than per cell, with the merges, conditional rules, banding, validation and notes that decide how a cell looks without being on the cellspreadsheets
search_spreadsheetsFind a spreadsheet by part of its title, by text inside it, by owner or by when it changeddrive.readonly
find_in_spreadsheetSearch one spreadsheet for text or an RE2 pattern and get back A1 addresses, saying whether each match was in a value, in the formula under it, or in a note beside itspreadsheets
create_spreadsheetA new spreadsheet, optionally with extra sheets and seed values. Returns its card, including the id every later call needsspreadsheets
write_valuesWrite a rectangle, refusing first anything the write would destroy that you cannot see, then reporting every value Google stored differently from how it was sent. An overwrite carries the checkpoint of what it replacesspreadsheets
append_rowsAdd rows after a block of data and report where they actually landed — Google decides the destination, and the same sheet given different ranges appends in different places. It inserts, so it never writes over a rowspreadsheets
format_cellsNumber format, font, colors, borders, alignment, wrapping, merges and notes, applied in one atomic batch. A merge, a clear and a note are the three that take something away, and each is refused until acknowledgedspreadsheets
manage_rangeAdd, update or delete what is attached to a range: a named range, a protected range, a validation rule, a table and the types of its columns, banding, or a conditional format rule or color scale. Existing ones are named by the range they cover, not by an idspreadsheets
transform_rangeSort, replace, trim, de-duplicate, split, shuffle, fill, copy or move a range — the operations that move data without you naming its new address, so each reads what it would land on firstspreadsheets
manage_anchorLabel a row, column or sheet so it can be found again after the spreadsheet has been edited around it. An anchor follows its row through inserts, deletes, moves and sorts, where an A1 address goes stale the moment somebody inserts a row. Pass anchor:<name> anywhere a range or band is taken, except in delete_dimensions and clear_values, which take the rows or range itself so the call shows what goesspreadsheets
manage_chartAdd, update, move, delete or list charts and slicers. A chart floats above the grid, so adding one overwrites nothing, and its data is named in A1, one range per series. A listing reports which charts have lost their series — what deleting a charted column does, and what nothing in Sheets tells youspreadsheets
manage_pivot_tableAdd, update, delete or list pivot tables, with groups by date or number ranges, filters and calculated values. Columns are named in A1 or by their heading, never by counting, and every result reports the rectangle the table covers right now: the size is computed from the data rather than chosen. A listing reads every rule back in the spelling the tool takesspreadsheets
connect_data_sourceOff by default: connect a BigQuery query or table through Connected Sheets. Google makes a sheet for it and runs the query, charged to the Cloud project you name, now and on every refreshspreadsheets, bigquery.readonly
manage_data_sourceOff by default: refresh one Connected Sheets data source, cancel a refresh, or list what is connected. get_spreadsheet already says whether a spreadsheet has one, with no extra scopespreadsheets, bigquery.readonly
read_cell_commentsThe comment threads on a spreadsheet's cells: the cell each is on now, open or resolved, who it is assigned to, and every post. A thread follows its cell as rows move, and one whose row was deleted is still listed, without a cellspreadsheets
manage_cell_commentComment on a cell, reply, edit a post, resolve or reopen. Google emails an assignee, and may notify an address the text names, which is how this server reaches someone outside the spreadsheetspreadsheets
manage_sheetAdd, rename, duplicate, copy to another spreadsheet, hide, unhide, reorder, resize, freeze or color a sheetspreadsheets
edit_dimensionsInsert, move, resize, auto-size, group, ungroup, hide or unhide rows and columnsspreadsheets
delete_dimensionsDestructive, off by default: remove rows or columns and the data on them, having counted what that isspreadsheets
clear_valuesDestructive, off by default: clear a range's values and keep its formatting, notes and validation rulesspreadsheets
delete_sheetDestructive, off by default: delete a sheet and everything on it, having counted what that isspreadsheets
delete_cell_commentDestructive, off by default: delete a comment thread with its replies, or one reply. Resolving keeps it, and is usually what is wantedspreadsheets
delete_data_sourceDestructive, off by default: delete a Connected Sheets data source, the sheet Google made for it, and everything on that sheet; Google unlinks what was built on the source. The call names that sheet's title. Needs no BigQuery scope, so it reaches a source somebody else connectedspreadsheets

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.

URIWhat it is
gsheets://{spreadsheet}The card: every sheet with its exact title, id and size, plus named ranges, tables and protected ranges. Reads no cells
gsheets://{spreadsheet}/{sheet}That sheet's used range as CSV — the rows and columns holding something, not the sheet's allocated size. The sheet title is percent-encoded

Install

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

    ScopeWhat it is for
    https://www.googleapis.com/auth/spreadsheetsEverything this server does inside a spreadsheet
    https://www.googleapis.com/auth/drive.readonlyFinding spreadsheets, their owner and modified time, and the account's address; never a write

    With GSHEETS_ENABLE_DATA_SOURCES=true, add a third:

    ScopeWhat it is for
    https://www.googleapis.com/auth/bigquery.readonlyconnect_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:

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

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

Connect a client

Claude Code:

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

Any client that takes a JSON server list:

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

SettingRegisters
GSHEETS_READ_ONLY=trueThe read tools only, with read-only scopes
defaultThe reads and the writes that refuse to destroy what they cannot see
GSHEETS_ENABLE_DESTRUCTIVE=trueAdds the deletes, each needing confirm: true
GSHEETS_ENABLE_DATA_SOURCES=trueAdds the Connected Sheets tools, and the BigQuery scope at login
GSHEETS_ALLOW_EXTERNAL_FORMULAS=trueNo tool; lets a write create a formula that fetches a URL or pulls in another spreadsheet

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:

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

bash
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.

Source: README.md at commit e830da5

Tools

0
SourceWeft started this package once in an isolated sandbox, without credentials, to list its tools. That failed: the package type cannot run in the sandbox.

Version history

13
  1. v4.2.1LatestNov 4, 2026
  2. v4.2.0Nov 1, 2026
  3. v4.1.1Oct 25, 2026
  4. v4.1.0Oct 24, 2026
  5. v4.0.0Oct 23, 2026
  6. v3.1.2Oct 10, 2026
  7. v3.1.1Oct 9, 2026
  8. v3.0.2Oct 1, 2026
  9. v3.0.0Sep 30, 2026
  10. v2.0.0Sep 27, 2026
  11. v1.5.1Sep 19, 2026
  12. v1.5.0Sep 18, 2026
  13. v1.4.0Sep 17, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts