mcp-google-sheets-rw

MCP server for Google Sheets with read AND write.

Works with any Google spreadsheet — trackers, CRMs, registries, or any Excel-style sheet living on Google.

Why another Google Sheets MCP?

• Read without credentials. Any sheet shared by link is readable (gviz export) — no Google Cloud setup needed to start.

• Server-side filtering. query filters rows on the server, so you never dump the whole 500-row spreadsheet into the model's context.

• Write by human names. Address columns by header name and rows by content query — not by A1 notation.

• update_by_query — the killer feature: "set Status = Rejected in every row containing Acme".

• Handles a title row above the header row automatically.

• Lightweight: Bun + a single dependency.

Related MCP server: Google Sheets MCP Server

Tools

Install

git clone https://github.com/Ap1-Pie/mcp-google-sheets-rw
cd mcp-google-sheets-rw
bun install

Configure the service account (writes; 10 minutes, one time)

Reading works out of the box for link-shared sheets. Writing needs a service account:

1. Open console.cloud.google.com and create a project.

2. APIs & Services → Library → enable Google Sheets API.

3. APIs & Services → Credentials → Create credentials → Service account (no role needed).

4. Open the account → Keys → Add key → JSON → download. Put the file next to the server as service-account.json.

5. Copy the service account email (looks like xxx@yyy.iam.gserviceaccount.com).

6. Share your spreadsheet with that email as Editor.

Configure your MCP client

{
  "mcpServers": {
    "gsheets": {
      "command": "bun",
      "args": ["/absolute/path/to/mcp-google-sheets-rw/src/gsheets-rw.ts"],
      "env": {
        "GSHEETS_SPREADSHEET_ID": "1AbC...your-spreadsheet-id",
        "GSHEETS_SHEETS": "Sheet1",
        "GOOGLE_SERVICE_ACCOUNT_FILE": "/absolute/path/to/service-account.json"
      }
    }
  }
}

Security

• Never commit service-account.json — .gitignore already excludes it.

• Grant the service account access only to the specific spreadsheet it serves.

• Reads go through the public gviz export; only share by link what you consider public-readable.

Keywords

mcp, google sheets, google excel, spreadsheet, read, write, model context protocol, agent, llm

License

MIT