Google Sheets MCP

An MCP server that lets Claude work with your Google Sheets in place — no more "here's a new spreadsheet" every time.

Read data, edit cells inline with natural language, append rows, insert/delete rows and columns, fill formulas, format cells, and find & replace — all against the sheet you already have open.

Runs two ways from one codebase:

• Local — a .mcpb desktop extension for Claude Desktop and local Cowork sessions.

• Remote — a Cloudflare Worker you add as a custom connector, which also works in cloud Cowork sessions, claude.ai on the web, and mobile.

Built on the MCP TypeScript SDK v2 (2026-07-28 spec) and the Google Sheets API v4, with no Google SDK dependency — just fetch and WebCrypto, so the same code runs on Node and in V8 isolates.

Tools

Spreadsheet IDs can be given as bare IDs or full Google Sheets URLs. Rows are 1-based numbers and columns are letters, exactly as in the Sheets UI.

Related MCP server: Claude Google Sheets MCP Server

1. Google Cloud credentials (one-time, needed either way)

1. In Google Cloud Console, create or pick a project.

2. Enable the Google Sheets API and Google Drive API.

3. APIs & Services → OAuth consent screen: set it up, add yourself under Test users. Then click Publish app. This does not require Google's verification review — personal-use apps (under 100 known users) are exempt; you just click through an "unverified app" warning once during authorization. Publishing matters because while the app sits in Testing, Google revokes refresh tokens every 7 days. The local extension recovers automatically by re-opening the browser, but a remote deployment needs a manual re-mint each time.

4. APIs & Services → Credentials → Create Credentials → OAuth client ID → Desktop app. Save the Client ID and Client Secret.

The Sheets and Drive APIs are free to use, and this project never needs a Cloud billing account attached. Leaving billing unattached is the simplest guarantee against charges.

2a. Local install (Claude Desktop / local Cowork sessions)

npm install
npm run pack        # builds and produces google-sheets.mcpb (~1.7 MB)

Double-click google-sheets.mcpb, or Claude Desktop → Settings → Extensions → Install Extension…. Paste your Client ID and Secret into the extension settings. On first use a browser opens to authorize; the refresh token is cached at ~/.config/google-sheets-mcp/token.json.

The extension asks only for OAuth credentials. Service-account auth is still supported when running the server directly or remotely — set GOOGLE_SERVICE_ACCOUNT_KEY_FILE or GOOGLE_SERVICE_ACCOUNT_KEY in the environment instead.

Local MCP servers do not run in cloud Cowork sessions or on claude.ai — for those, use the remote deployment below.

2b. Remote install (cloud Cowork sessions, web, mobile)

Mint a refresh token — this runs the same browser consent flow and prints a long-lived token for the server to use:

GOOGLE_OAUTH_CLIENT_ID=…apps.googleusercontent.com \
GOOGLE_OAUTH_CLIENT_SECRET=… \
npm run mint-token

Pick a bearer token. This is the shared secret Claude must present on every request:

node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"

Deploy to Cloudflare Workers (free tier is plenty; the Worker is ~174 KB gzipped):

npx wrangler login
npx wrangler secret put MCP_BEARER_TOKEN            # the value you just generated
npx wrangler secret put GOOGLE_OAUTH_CLIENT_ID
npx wrangler secret put GOOGLE_OAUTH_CLIENT_SECRET
npx wrangler secret put GOOGLE_REFRESH_TOKEN        # from mint-token
npm run deploy

Wrangler prints a URL like https://google-sheets-mcp.<you>.workers.dev. Verify it with curl https://…/health — it should return ok.

Add it to Claude: Settings → Connectors → Add custom connector.

• If your Add-connector dialog has a Request headers section (beta, gradual rollout): URL https://google-sheets-mcp.<you>.workers.dev/mcp with header authorization: Bearer <your MCP_BEARER_TOKEN>.

• If it doesn't, put the token in the URL path instead: https://google-sheets-mcp.<you>.workers.dev/mcp/<your MCP_BEARER_TOKEN>.

Security notes

• The endpoint is public, so the bearer token is the only thing standing between the internet and your spreadsheets. Use a long random value and treat it like a password.

• Auth fails closed: if MCP_BEARER_TOKEN is unset, every request to /mcp is rejected with 401 rather than running unauthenticated.

• Token comparison is constant-time, so the secret can't be recovered by timing.

• GOOGLE_REFRESH_TOKEN grants access to every spreadsheet your account can open. To narrow that, use a service account instead (GOOGLE_SERVICE_ACCOUNT_KEY, inline JSON) and share only specific sheets with its email address.

• To revoke everything at once: myaccount.google.com/permissions.

Configuration reference

Scopes: spreadsheets (read/write) + drive.metadata.readonly (list/search files).

Development

npm install
npm run build       # compile to dist/
npm run typecheck   # tsc --noEmit
npm run pack        # build + package the .mcpb bundle
npm run dev:worker  # run the Worker locally via wrangler
npm run deploy      # deploy the Worker

src/
  index.ts          stdio entry point (local)
  worker.ts         Cloudflare Worker entry (remote) + bearer auth
  server.ts         server factory: registers all tool groups
  config.ts         credentials → token provider, shared by both entries
  google/
    auth.ts         fetch + WebCrypto token providers (refresh token, service account)
    client.ts       REST client for the Sheets/Drive endpoints used
    types.ts        minimal API types
  node/
    localOAuth.ts   Node-only desktop OAuth loopback flow
    mintToken.ts    CLI to print a refresh token for remote deploys
  tools/            one module per tool group (read, write, structure, format, advanced)
  utils/            A1-notation parsing, tool result/error helpers