Google Workspace MCP Server

gws-mcp-server

Maintenance mode. This project is stable and receives security fixes. New features aren't planned, but issues and pull requests are still welcome.

Google Workspace for AI agents: Gmail, Calendar, Drive, Sheets, Docs, Slides, Tasks, and Contacts as a curated set of 67 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 — gmaildraftscreate 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.

Shortened. The full README is on GitHub.