gws-mcp-server

<div align="center">

gws-mcp-server

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

    

<img src="docs/demo.gif" alt="Demo: an agent calls the calendar_events_list tool and gets events back (sample data)" width="800">

</div>

---

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 MCP readOnlyHint/destructiveHint annotations so clients can reason about side effects and surface clearer consent prompts.

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 send tool — the closest thing is gmail_drafts_create, which explicitly does not send. The token gws auth login mints is broader than that.

gws auth login opens a scope picker with nine scopes pre-selected, including gmail.modify (Google documents it as "Read, compose, and send emails"), full read-write drive, and cloud-platform. Pressing Enter accepts all of them. Run non-interactively and you get DEFAULT_SCOPES, which is the same list minus the picker.

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

One trap worth knowing: -s gmail does not narrow the picker to Gmail alone. cloud-platform is treated as a cross-service scope and is always included, pre-selected — deselect it manually if you use that flag.

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,gmail,tasks"
      ]
    }
  }
}

Claude Desktop (claude_desktop_config.json)

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

Options

| Flag | Description | Default | |------|-------------|---------| | --services, -s | Comma-separated list of services to expose | All services | | --gws-path | Path to the gws binary | gws |

Available services & tools

drive (9 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

sheets (4 tools)

• sheets_get — Get spreadsheet metadata
• sheets_values_get — Read cell values
• sheets_values_update — Write cell values
• sheets_values_append — Append rows

calendar (5 tools)

• calendar_events_list — List events
• calendar_events_get — Get event details
• calendar_events_insert — Create events
• calendar_events_update — Update events (only supplied fields change)
• calendar_events_delete — Delete events

docs (3 tools)

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

gmail (6 tools)

• gmail_messages_list — Search messages
• gmail_messages_get — Read a message
• gmail_threads_list — Search threads
• gmail_threads_get — Read a full thread
• gmail_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 via threadId). Drafts are never auto-sent

tasks (12 tools)

• tasks_tasklists_list — List task lists
• tasks_tasklists_get — Get a task list
• tasks_tasklists_insert — Create a task list
• tasks_tasklists_update — Update a task list (only supplied fields change)
• tasks_tasklists_delete — Delete a task list
• tasks_tasks_list — List tasks (filters: completed/hidden/due dates)
• tasks_tasks_get — Get a task
• tasks_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 reorder
• tasks_tasks_delete — Delete a task
• tasks_tasks_clear — Hide all completed tasks in a list

Update semantics: the _update tools (calendar events, tasks, task lists) use the Google API's patch verb — 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: 39 tools (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. The most useful contributions are new tool definitions in src/services.ts for high-value gws operations (see "Adding new tools" above). Keep the curated contract: a focused set of narrowly scoped tools, not a 1:1 mirror of every Google API surface. See SECURITY.md for how to report vulnerabilities.

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, and Tasks.

<a href="https://glama.ai/mcp/servers/conorbronsdon/gws-mcp-server"> <img width="380" height="200" src="https://glama.ai/mcp/servers/conorbronsdon/gws-mcp-server/badge" alt="gws-mcp-server MCP server" /> </a>

Companion tools:

• Transistor-MCP: the Transistor.fm MCP server. Episodes, transcripts, and download counts.
• 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