gws-mcp

An MCP server that lets an agent read from and append to a Google Sheet over a service account, so a scheduled task can write leads into a real CRM spreadsheet with no manual paste step and no human in the loop for the append itself.

What's shipped (P0)

• Transport: local stdio only. No remote HTTP transport yet.
• Auth: a Google Cloud service account (AUTH_MODE=service_account, the only mode this build implements). No user OAuth flow, no token store.
• Tools: exactly three.
  • drive_find: find a Sheet by name.
  • sheets_read_range: read a range in A1 notation.
  • sheets_append_rows: append rows to a tab, with optional dedup and a dry_run preview.
• Scopes: exactly https://www.googleapis.com/auth/spreadsheets and https://www.googleapis.com/auth/drive.readonly. Never full https://www.googleapis.com/auth/drive.
• Every write, live or dry run, lands two lines (an intent line and an outcome line) in an append-only JSONL audit log. Row contents are never logged.

Env vars this build actually reads: AUTH_MODE, exactly one of GOOGLE_SA_KEY_PATH or GOOGLE_SA_KEY_JSON, and AUDIT_LOG_PATH. See .env.example.

Docs, Slides, and a remote OAuth connector are later phases. None of that is built yet.

Setup

See docs/SETUP.md for the full walkthrough: creating the service account, sharing a spreadsheet with it, configuring env vars, registering with claude mcp add, reading the audit log, and running the integration suite. This file stays intentionally brief; that one is the source of truth for getting a working server.

Running the tests

npm test              # unit + contract, no network, no credentials
npm run typecheck
npm run lint
npm run test:integration   # gated behind GWS_INTEGRATION=1; see docs/SETUP.md

Design docs

• Spec: docs/superpowers/specs/2026-07-31-gws-mcp-p0-design.md
• Plan: docs/superpowers/plans/2026-07-31-gws-mcp-p0.md