gws-mcp

Minimal Google Workspace MCP server for Claude Code. Gmail, Drive, Docs, Sheets, and Calendar across two fixed accounts. Thirteen tools, roughly 1,750 schema tokens. It replaces workspace-mcp, whose same-service surface measured 65 tools and roughly 28,000 tokens.

Tool surface

Every tool takes account, an enum of personal and professional. The alias-to-email map comes from GWS_MCP_PERSONAL_EMAIL and GWS_MCP_PROFESSIONAL_EMAIL, set in .envrc.

No tool can permanently delete anything. Trashing is the only removal the tool surface performs. The stored token itself carries the full drive scope, which Google classifies as restricted, so guard the token store, and know that the credential could do more than the tools allow.

Related MCP server: Google Workspace MCP

Google Cloud setup (one time)

1. Create a project at https://console.cloud.google.com/projectcreate. The string "google" is banned in project IDs and app names.

2. Enable five APIs: Gmail, Google Drive, Google Docs, Google Sheets, Google Calendar.

3. Google Auth Platform: External audience, no test users.

4. Publish to Production immediately. A Testing-status app expires every refresh token 7 days after consent.

5. Create a Desktop-app OAuth client. Copy the client ID and secret.

6. Do not submit the app for verification. The unverified-app warning at consent time is expected.

Secrets and environment

The client credentials live in safetybox:

gwsmcp/google-client-id      -> GWS_MCP_GOOGLE_CLIENT_ID
gwsmcp/google-client-secret  -> GWS_MCP_GOOGLE_CLIENT_SECRET

.envrc is not committed. Copy .envrc.example, fill in the two account emails, then run direnv allow. The safetybox line loads both client credentials with one identity unlock, reading the passphrase from passage via secret-get. Only the auth CLI reads these variables. OAuth tokens land in ~/.local/share/gws-mcp/tokens.db, file mode 0600, directory 0700, never in the repo.

Install and authenticate

uv sync
uv run gws-mcp-auth personal
uv run gws-mcp-auth professional

Each run opens a browser. Sign in as the matching account and click through Advanced at the unverified-app warning. The CLI verifies the signed-in address against the alias and refuses to save a mismatch.

A scope added to SCOPES never reaches an already-stored grant. Re-run gws-mcp-auth <alias> for each account, otherwise the new tool fails with an insufficient-scope 403.

Then verify with the live read-only smoke script:

uv run python scripts/smoke.py

Register with Claude Code

claude mcp add gws-mcp -s user -- uv run --directory /Users/samuelstidham/code/samuel-stidham/gws-mcp gws-mcp

Testing

uv run pytest

The suite fakes every Google endpoint with respx and never touches the live APIs. It covers account routing, the single-refresh 401 rule, rate-limit backoff, MIME decoding, label resolution, batch Drive semantics, Sheets append, protocol round-trips, stdout cleanliness, and the schema budget.

Measure the schema at any time:

uv run python scripts/measure_schema.py
uv run python scripts/measure_schema.py --probe uvx workspace-mcp --tools gmail drive docs sheets

The probe spawns the child with the MCP SDK's safe environment allowlist, so no secret from your shell reaches it. Pass --env KEY=VALUE for anything the probed server genuinely needs.

Known failure modes

• A Google password change revokes that account's refresh token. Re-run gws-mcp-auth <alias>. A running server picks up the new grant on its next refresh, no restart needed.

• A refresh token unused for six months expires.

• The server refreshes once on 401 and then fails with the exact re-auth command in the error message. A dead grant fails a whole batch immediately instead of retrying per item.

• sheets_write uses USER_ENTERED, so a value starting with = becomes a live formula. That is deliberate, and it means untrusted text should not be written to sheets verbatim.