gws-mcp-server

Google Workspace for AI agents: Gmail, Calendar, Drive, Sheets, Docs, Slides, and Tasks as a curated set of 49 Model Context Protocol tools, built on the official Google Workspace CLI (gws).

Why?

The gws CLI had a built-in MCP server that was removed in v0.8.0 because it exposed 200-400 tools — causing context window bloat in MCP clients. This server takes a curated approach: you choose which Google services to expose, and only a focused set of high-value, narrowly scoped operations are registered as tools. Every tool declares all four MCP annotation hints — readOnlyHint, destructiveHint, idempotentHint, openWorldHint — so clients can reason about side effects, know which writes are safe to retry, and surface clearer consent prompts. This is the permissions leg of trust infrastructure for agents: a deliberately narrow tool surface, side effects declared on every tool, and no freestanding send tool — the only outbound email an agent can trigger is calendar invite/update notifications, opt-in via sendUpdates and off by default.

Prerequisites

• Node.js 18+
• gws CLI installed and authenticated (npm install -g @googleworkspace/cli && gws auth login)

Grant fewer scopes than the default

This server exposes no freestanding send tool — gmail_drafts_create explicitly does not send, and the only outbound email an agent can trigger is calendar invite/update notifications via sendUpdates, which is enum-validated and defaults to none. The token gws auth login mints is broader than that.

gws auth login opens a scope picker listing nine scopes. The default grant is seven: full read-write drive, spreadsheets, gmail.modify (Google documents it as "Read, compose, and send emails"), calendar, documents, presentations, and tasks — the same seven you get running non-interactively as DEFAULT_SCOPES.

The other two rows are Cloud Pub/Sub and Cloud Platform, and neither is part of the default grant — gws auth login --help describes --full as "Request all scopes incl. pubsub + cloud-platform."

Which rows start checked has not been verified against a live picker — the seven above are the documented default grant, not an observation of the TUI. Read the checkboxes before pressing Enter rather than trusting this paragraph.

So the token on disk can send mail and rewrite Drive even though nothing here will. Deselect what you do not need in the picker, or:

gws auth login --readonly    # read-only across services

-s gmail limits the picker to Gmail, per the flag's own help text ("Comma-separated service names to limit scope picker"). It cannot pull in cloud-platform or pubsub, because those two are reachable only through --full.

On Linux there is no keyring, and the encryption key is a file next to the data it encrypts. gws enables the keyring crate's native backends only for macOS and Windows; on every other platform the dependency is declared with no backend feature, so the store falls through to writing .encryption_key into ~/.config/gws/. That file is not a backup of a key held elsewhere — it is the key, and the credential store's own doc comment says it is never deleted. Setting GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=file changes nothing there because that is already the only path. On macOS and Windows the key file is removed once the OS keyring holds the key. If you run this headless on Linux, treat ~/.config/gws/ as a password file: anyone who can read the directory has the credentials.

Quick start

# Install
npm install -g gws-mcp-server

# Or run from source
git clone https://github.com/conorbronsdon/gws-mcp-server.git
cd gws-mcp-server
npm install && npm run build

Configuration

Claude Code (.mcp.json)

{
  "mcpServers": {
    "google-workspace": {
      "command": "npx",
      "args": [
        "gws-mcp-server",
        "--services", "drive,sheets,calendar,docs,slides,gmail,tasks"
      ]
    }
  }
}

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "google-workspace": {
      "command": "npx",
      "args": [
        "gws-mcp-server",
        "--services", "drive,sheets,calendar"
      ]
    }
  }
}

Options

--read-only

--read-only registers 22 tools instead of 49. Every tool that writes to Google is left unregistered, so it never appears in tools/list and there is nothing for an agent to call — including gmail_drafts_create, which is a write even though it never sends. drive_files_download stays, since it reads.

gws-mcp-server --read-only
gws-mcp-server --read-only --services drive,calendar   # combines with -s

This constrains the agent, not the credential. The token on disk keeps whatever scopes it was granted, and anything else on the machine can still use it. gws auth login --readonly is what narrows the token; the two are complementary. For an MCP server the agent is the threat model, but that is the limit of the claim.

Trimming context cost

Every registered tool rides along in each conversation: the full registry is roughly 34 KB of tools/list payload (~8.7K tokens) that your MCP client loads before anything else happens. The two flags above compose, and dropping whole services you don't use is the cheapest context win there is:

gws-mcp-server --services calendar                       # calendar assistant: 6 tools
gws-mcp-server --services drive,docs                     # document work, nothing else
gws-mcp-server --read-only --services drive,docs,sheets  # research setup: reads only

In .mcp.json or claude_desktop_config.json, the same trimming is just editing the args array:

"args": ["gws-mcp-server", "--services", "drive,calendar"]

A service's tool count (headers below) tracks its context cost: dropping tasks (12 tools) saves the most, docs (3 tools) the least. There is no per-tool exclude flag today — if service granularity is too coarse for your setup, open an issue describing the split you need.

Available services & tools

drive (12 tools)

• drive_files_list — Search and list files
• drive_files_get — Get file metadata
• drive_files_create — Create files (with optional upload)
• drive_files_copy — Copy files (useful for format conversion)
• drive_files_update — Update file metadata/content
• drive_files_delete — Delete files
• drive_files_export — Export Google Workspace files (Doc, Sheet, Slide) to other formats
• drive_files_download — Download file content (text inline, binary as base64 or saved to a path; Google-native files are exported to a readable format)
• drive_permissions_create — Share files
• drive_permissions_list — List all permissions on a file (audit sharing state, e.g. check for public access)
• drive_permissions_update — Change an existing permission's role (e.g. reader to writer); downgrades remove capabilities. Ownership transfers are not supported.
• drive_permissions_delete — Revoke a permission from a file

sheets (5 tools)

• sheets_get — Get spreadsheet metadata
• sheets_values_get — Read cell values
• sheets_values_update — Write cell values
• sheets_values_append — Append rows
• sheets_batchUpdate — Apply updates to a spreadsheet (conditional formatting, cell/border formatting, adding sheets, and more; delete requests are permanent)

calendar (6 tools)

• calendar_events_list — List events
• calendar_events_get — Get event details
• calendar_events_insert — Create events, optionally with attendees. sendUpdates controls invitation email (default none — no email, though the event may still appear on attendees' calendars depending on their settings)
• calendar_events_update — Update events (only supplied fields change — except attendees, which replaces the whole list; omitted attendees are uninvited). Same sendUpdates support as insert
• calendar_events_delete — Delete events
• calendar_freebusy_query — Query free/busy information for one or more calendars over a time range

docs (3 tools)

• docs_get — Get document content
• docs_create — Create documents
• docs_batchUpdate — Apply document updates

slides (5 tools)

• slides_get — Get a presentation's slides, layouts, masters, and page elements
• slides_create — Create a blank presentation
• slides_batchUpdate — Apply updates (insert/update/delete slides, text, shapes, tables, etc)
• slides_pages_get — Get a single page (slide, layout, or master)
• slides_pages_getThumbnail — Get a thumbnail image URL for a page