# 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](https://bun.sh) + a single dependency.

## Tools

| Tool | What it does |
|---|---|
| `read_sheet` | Read a sheet. Optional `query` (substring filter over any column) and `limit`. |
| `list_sheets` | List sheets of the spreadsheet (via API when a key is configured). |
| `write_cell` | Set a cell: `row` (1-based) + `header` (column name) + `value`. |
| `append_row` | Append a row to the end from a `{header: value}` object. |
| `update_by_query` | Set `header`=`value` in all rows where any column contains `query`. |

## Install

```bash
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](https://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

```json
{
  "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"
      }
    }
  }
}
```

| Env var | Meaning |
|---|---|
| `GSHEETS_SPREADSHEET_ID` | Spreadsheet ID from its URL (required) |
| `GSHEETS_SHEETS` | Comma-separated sheet names; the first is the default |
| `GOOGLE_SERVICE_ACCOUNT_FILE` | Path to the service account JSON (optional; enables writes) |

## 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