# gws-mcp

> [!IMPORTANT]
> The OAuth app behind this repo is published but **not verified** by Google,
> and it serves only my own two Google accounts. The consent screen shows the
> "Google hasn't verified this app" warning by design, and its unverified user
> cap leaves no room for anyone else. To run this yourself, create your own
> Google Cloud project and Desktop OAuth client with the same three scopes. The
> setup section below covers every step, and the account emails come from
> environment variables, never from code. If enough demand shows up I may put
> the app through Google's verification process. Open an issue if you want
> that.

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

| Tool | Purpose |
| --- | --- |
| `gmail_search` | Gmail query syntax in, message metadata out |
| `gmail_read` | Decoded body of one message or a whole thread |
| `gmail_send` | Send or draft, `thread_id` makes it a reply |
| `gmail_modify` | Label names on messages or threads, covers archive, read state, star, trash |
| `drive_search` | Drive query plus MIME filter |
| `drive_get` | Docs export as Markdown, Sheets as CSV, text files raw |
| `drive_update` | Batch move, rename, trash. Per-file results |
| `drive_folder_create` | New folder under a parent |
| `docs_create` | New Doc from Markdown |
| `docs_update` | Append text or replace all occurrences |
| `sheets_read` | A1 range in, values out |
| `sheets_write` | Write or append to an A1 range |
| `calendar_event_create` | New event, all-day or timed, optional RRULE recurrence and popup reminder |

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.

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