Google Sheets MCP Server

Google Sheets MCP Server

An MCP server that lets Claude, Cursor or any other MCP client read and write your Google Sheets: list a spreadsheet's tabs, read ranges, append or update rows, and export an Apify dataset to a tab.

It signs in with your own Google service account, so there's no shared quota, no OAuth app to approve, and nothing that expires. The service account can only open sheets you share with it.

Two ways to use it:

• Hosted on Apify (no install): apify.com/oldjard/google-sheets-mcp. Apify starts the server when your agent calls it and stops it when it goes quiet. It is paid per use, billed to your own Apify account (prices below).
• Self-hosted (free): clone this repo and run it yourself. Same code.

Tools

Tool	What it does
list_sheets	Lists a spreadsheet's tabs, with their size and link
read_range	Reads cells (Leads!A1:D50, A1:D50, or a whole tab). Long tabs come back in pages, with the next range to read
append_rows	Adds rows under the last one. Objects are matched to the header by name (new fields become columns). Arrays are written as they are. Can skip rows already in the tab
update_range	Overwrites cells from a top-left cell, and grows the tab if needed
export_dataset	Writes an Apify dataset to a tab: append, replace, or only new rows

Values are written as plain values, never as formulas. One call reads or writes at most 5,000 rows. If a tool can't do something (sheet not shared, a wrong tab name, a missing key), it returns a plain-English fix, for example the exact email to share the sheet with.

Google setup (about 5 minutes, once)

You need a Google service account: a robot Google user that only gets access to the sheets you share with it. It's free, and Google asks for no billing details to use the Sheets API.

1. Open console.cloud.google.com, create a project and select it.
2. Open the Google Sheets API page and click Enable.
3. IAM & Admin > Service Accounts > Create service account. Name it, skip the optional role step, click Done.
4. Open the service account, Keys > Add key > Create new key > JSON. A .json file downloads.
5. Copy its client_email. Share each Google Sheet your agent should use with that email as Editor.
6. Turn the key into one line of base64: base64 -w0 key.json (on macOS: base64 -i key.json).

Some Google Workspace organizations block service-account keys. If step 4 says key creation is disabled by policy, use a personal Google account for the project; the sheet can live anywhere as long as it's shared with the email.

Connect: hosted on Apify

Use the URL https://oldjard--google-sheets-mcp.apify.actor/mcp with two headers. For Claude Code:

claude mcp add --transport http google-sheets https://oldjard--google-sheets-mcp.apify.actor/mcp \
  --header "Authorization: Bearer <your Apify API token>" \
  --header "X-Google-Service-Account-Key: <the base64 line>"

Other clients take the same URL and headers in their JSON config.

Pricing (hosted): $0.001 per successful tool call, $0.0004 per row that export_dataset writes. Failed calls, header rows and rows skipped as duplicates are free. Each server start costs $0.00005. As with any Apify Standby Actor, Apify also bills the platform usage of the run while your agent is connected and for a short idle period after (the server runs at 256 MB, so this is a fraction of a cent per session). The key travels over HTTPS to your own run, is held in memory only, and is never logged or stored.

Connect: self-hosted

Needs Node.js 24 or newer.

git clone https://github.com/joshuawhite389/google-sheets-mcp && cd google-sheets-mcp
npm install
PORT=3000 npm run serve

Then point your client at http://localhost:3000/mcp with the X-Google-Service-Account-Key header (no Apify token needed; export_dataset then reads datasets from the local ./storage folder). The Dockerfile builds the same server for Apify; to run it elsewhere, set APIFY_META_ORIGIN=STANDBY and ACTOR_WEB_SERVER_PORT.

Limits worth knowing

• Google allows 10 million cells per spreadsheet and 50,000 characters per cell.
• A service account gets Google's standard quota of 60 write requests per minute. Rate limits and Google hiccups are retried with backoff.

Development

npm test          # unit tests against a fake Google API that verifies the signed sign-in
npm run e2e       # the real server process, driven by a real MCP client, against the fake Google
npm run typecheck

Related

Dataset to Pinecone & Qdrant Vector Export (an Apify Actor, not an MCP server) chunks and embeds a scraped dataset into your own Pinecone or Qdrant index.

License

MIT