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+
gwsCLI 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. It also replaces any credential you already have rather than adding to it. To add a service to an existing login, use gws-mcp-server auth login.
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.
Contacts needs a scope outside the default grant
The people_* tools need the contacts scope, which the default gws auth login (and the seven-scope grant described above) does not request.
Add Contacts with gws-mcp-server auth login -s people, not gws auth login -s people. gws's own filtered login replaces the saved credential with only the filtered scopes, so it drops Drive, Gmail, Calendar and everything else you had granted (#68, tracked upstream in googleworkspace/cli#673). This server's auth login does incremental authorization instead:
gws-mcp-server auth login -s people # keep existing scopes, add contacts
gws-mcp-server auth login -s people --dry-run # print the gws command first
It reads the scopes the saved credential holds from gws auth status, adds the requested services' scopes, and runs gws auth login --scopes <existing + new>. You consent once in the browser, and afterwards it re-reads gws auth status and exits non-zero if any scope you asked for (old or new) wasn't granted, for example because a box was unticked on Google's consent screen. gws saves whatever the consent screen granted, so an unticked box does remove that scope from the saved credential. Before the browser opens, and again if anything is missing afterwards, the command prints the gws auth login --scopes "..." command that re-requests the complete list. It needs a client configured for gws auth login already, and it exits without changing anything if the credential already covers the services.
gws auth status discovers scopes live (refresh-token exchange plus Google's token-info lookup), so the scopes field can be missing when that fails. When a saved credential exists but its scopes can't be read, auth login refuses rather than guessing; fix the status lookup and retry. If you really mean to start over with only the requested scopes, pass --replace. With no saved credential at all it is a first login and requests just the services you name.
If you prefer to run gws directly, pass the complete list yourself. For a credential that used exactly the default seven scopes described above:
gws auth login --scopes "https://www.googleapis.com/auth/drive,https://www.googleapis.com/auth/spreadsheets,https://www.googleapis.com/auth/gmail.modify,https://www.googleapis.com/auth/calendar,https://www.googleapis.com/auth/documents,https://www.googleapis.com/auth/presentations,https://www.googleapis.com/auth/tasks,https://www.googleapis.com/auth/contacts"
The People API must also be enabled on your own GCP project — a one-time step separate from OAuth, since a new scope grant doesn't enable a new API by itself:
gcloud services enable people.googleapis.com --project=<your-project-id>
Without both steps, people_* tools fail: a missing scope surfaces as a 401/403 from Google, and a disabled API surfaces as a distinct 403 naming the API and a console link to enable it.
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"
]
}
}
}
Contacts is opt-in because it needs additional authentication and API setup.
After completing the Contacts prerequisites,
append people to the service list:
"args": ["gws-mcp-server", "--services", "drive,calendar,people"]
Claude Desktop (claude_desktop_config.json)
{
"mcpServers": {
"google-workspace": {
"command": "npx",
"args": [
"gws-mcp-server",
"--services", "drive,sheets,calendar"
]
}
}
}
Options
On Windows, npm's gws.cmd is resolved to its JavaScript entry point and run with Node. --gws-path or GWS_BINARY may also point directly to a JavaScript entry point or .exe.
--read-only
--read-only registers 26 tools instead of the default 61. 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. Explicitly adding people raises those counts to 29 read-only tools out of 67 total.
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 default registry is roughly 46 KB of tools/list payload (~11.8K tokens); opting into people raises the full registry to roughly 52 KB (~13.2K tokens). 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 drive (24 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 (24 tools)
drive_files_list— Search and list filesdrive_files_get— Get file metadatadrive_files_create— Create files (with optional upload)drive_files_copy— Copy files (useful for format conversion)drive_files_update— Update file metadata/contentdrive_files_delete— Delete filesdrive_files_export— Export Google Workspace files (Doc, Sheet, Slide) to other formatsdrive_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 filesdrive_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. Use the dedicated transfer tools below for ownership changes.drive_permissions_delete— Revoke a permission from a filedrive_permissions_transferOwnership— Immediately transfer ownership to another Google Workspace account in the SAME organization, downgrading the current owner to writer; sends a mandatory notification email; not supported for shared drive filesdrive_permissions_proposeOwnershipTransfer— Propose transferring ownership between personal/consumer accounts; the recipient must separately accept (mandatory email notification), this doesn't transfer it outrightdrive_comments_list— List comments on a file (works on any Drive file, not just Docs/Sheets/Slides)drive_comments_get— Get a single commentdrive_comments_create— Add a comment, optionally anchored to an app-defined region (Workspace editors still show it as unanchored)drive_comments_update— Change a comment's text (author-only)drive_comments_delete— Permanently delete a comment (author-only)drive_replies_list— List replies to a commentdrive_replies_get— Get a single replydrive_replies_create— Reply to a comment, or resolve/reopen it via theactionfielddrive_replies_update— Change a reply's text (author-only)drive_replies_delete— Permanently delete a reply (author-only)
sheets (5 tools)
sheets_get— Get spreadsheet metadatasheets_values_get— Read cell valuessheets_values_update— Write cell valuessheets_values_append— Append rowssheets_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 eventscalendar_events_get— Get event detailscalendar_events_insert— Create events, optionally withattendees.sendUpdatescontrols invitation email (defaultnone— no email, though the event may still appear on attendees' calendars depending on their settings)calendar_events_update— Update events (only supplied fields change — exceptattendees, which replaces the whole list; omitted attendees are uninvited). SamesendUpdatessupport as insertcalendar_events_delete— Delete eventscalendar_freebusy_query— Query free/busy information for one or more calendars over a time range
docs (3 tools)
docs_get— Get document contentdocs_create— Create documentsdocs_batchUpdate— Apply document updates
slides (5 tools)
slides_get— Get a presentation's slides, layouts, masters, and page elementsslides_create— Create a blank presentationslides_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
gmail (6 tools)
gmail_messages_list— Search messagesgmail_messages_get— Read a messagegmail_threads_list— Search threadsgmail_threads_get— Read a full threadgmail_threads_modify— Add/remove labels on a thread (archive, mark read, star)gmail_drafts_create— Create a draft (plain text and/or HTML, with reply threading viathreadId). Drafts are never auto-sent
tasks (12 tools)
tasks_tasklists_list— List task liststasks_tasklists_get— Get a task listtasks_tasklists_insert— Create a task listtasks_tasklists_update— Update a task list (only supplied fields change)tasks_tasklists_delete— Delete a task listtasks_tasks_list— List tasks (filters: completed/hidden/due dates)tasks_tasks_get— Get a tasktasks_tasks_insert— Create a task (optionally nested or positioned)tasks_tasks_update— Update a task (only supplied fields change; common use: mark complete)tasks_tasks_move— Move a task within/across lists or reordertasks_tasks_delete— Delete a tasktasks_tasks_clear— Hide all completed tasks in a list
people (6 tools)
Needs the contacts scope and an enabled People API — see Contacts needs a scope outside the default grant.
people_people_get— Get a contact by resource name (orpeople/mefor the authenticated user)people_people_searchContacts— Search contacts by name, email, phone, or organizationpeople_people_createContact— Create a new contactpeople_people_updateContact— Update a contact (requires the current etag in the request body)people_people_deleteContact— Permanently delete a contactpeople_connections_list— List the authenticated user's contacts
Update semantics: the
*_updatetools (calendar events, tasks, task lists) use the Google API'spatchverb — they merge the fields you supply and leave the rest untouched. To clear an existing value, pass it explicitly (e.g. an empty string) rather than omitting it.
Total: 67 supported tools; 61 enabled by default (vs 200-400 in the old implementation)
Adding new tools
Edit src/services.ts to add tool definitions. Each tool maps directly to a gws CLI command:
{
name: "drive_files_list", // MCP tool name
description: "List files in Drive", // Shown to AI
command: ["drive", "files", "list"],// gws CLI args
params: [ // Maps to --params JSON
{ name: "q", description: "Search query", type: "string", required: false },
],
bodyParams: [ // Maps to --json body
{ name: "name", description: "File name", type: "string", required: true },
],
}
Typed errors
Tool call failures are mapped to a typed error hierarchy (src/errors.ts): AuthenticationError (401/403), RateLimitError (429), ValidationError (400), NotFoundError (404, with a shared-drive access hint for drive commands), and ServerError (5xx), all extending a base GwsError. Unlike an HTTP API client, this server has no response object to read a status code from — it spawns the gws CLI as a subprocess and only sees plain text (stdout/stderr, or a rejected promise's .message). mapGwsErrorToTyped() recovers a status-like code from that text, handling both a raw JSON error body (Google's own {"error":{"code":...,"message":...}} shape) and plain text containing an HTTP-status-like token (e.g. "Error 404: ..."). If neither pattern is found, the original message passes through unchanged rather than forcing an invented status onto it.
Architecture
MCP Client (Claude) ←→ stdio ←→ gws-mcp-server ←→ gws CLI ←→ Google APIs
The server is a thin wrapper: it translates MCP tool calls into gws CLI invocations, passes --params and --json as appropriate, and returns the JSON output. Authentication stays in the gws CLI — this server never sees or stores your Google credentials.
Development
git clone https://github.com/conorbronsdon/gws-mcp-server.git
cd gws-mcp-server
npm ci
npm run lint # type-check
npm run build
npm test # vitest, mocks the executor layer — no real gws calls
Contributing
Issues and pull requests are welcome. Keep the curated contract: a focused set of narrowly scoped tools, not a 1:1 mirror of every Google API surface. Before writing a PR for a new service, open an issue describing the use case, required scopes and side effects; docs/scope-policy.md explains what belongs here and what fits better as a companion server. Improvements to existing tools are welcome directly. See SECURITY.md for how to report vulnerabilities.
Companion servers
Services outside the curated set can ship as separate MCP servers that run alongside this one, each with its own scope grant. Community companion servers that declare side effects on every tool and add no freestanding send action will be listed here.
Other options
This server is deliberately narrow: a curated tool surface, side effects declared on every tool, no freestanding send tool. That is the right trade for some workflows and the wrong one for others. The real alternatives:
Worth saying plainly: Google's official Gmail MCP server is also draft-only, with no send tool — the curated-surface argument is no longer contrarian. What this server still does that those don't: Google Tasks (Google's official lineup has no Tasks server), all four MCP annotation hints on every tool, a local stdio server with no preview application or plan gating, and --read-only as a single flag.
The analytics siblings
These are separate credential families, not one login: Workspace authenticates with gws auth login, Search Console with a webmasters OAuth credential, YouTube Analytics with a yt-analytics.readonly OAuth credential, GA4 with Application Default Credentials scoped analytics.readonly. Nothing here shares a token with anything else.
About
Built and maintained by Conor Bronsdon. I host the Chain of Thought podcast, which covers AI infrastructure, developer tools, and how practitioners actually use this stuff. I built this to give the agent workflows that run the show safe, curated access to Gmail, Calendar, Drive, Sheets, Docs, Slides, Tasks, and Contacts.
Companion tools:
- Transistor MCP: Transistor.fm's official MCP server. Episodes, publishing, and analytics.
- substack-mcp: read posts and manage drafts on Substack, safe for agent workflows.
- podcastindex-mcp: the Podcast Index MCP server, search by person or topic, trending shows, feed health.
- op3-mcp: podcast analytics through OP3. Downloads, geography, apps. Read-only.
- ai-tools-for-creators: a curated list of AI skills and MCP servers for people who ship ideas for a living.
More at chainofthought.show and on X.
Disclaimer
This is an independent personal project, not affiliated with, sponsored by, or endorsed by any company. All views expressed are my own.
License
MIT
