# 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](https://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](https://console.cloud.google.com), create a project and select it.
2. Open the [Google Sheets API page](https://console.cloud.google.com/apis/library/sheets.googleapis.com) 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](https://apify.com/oldjard/dataset-to-pinecone-qdrant) (an Apify Actor,
not an MCP server) chunks and embeds a scraped dataset into your own Pinecone or Qdrant index.

## License

MIT