gws-mcp-server

Google Workspace for AI agents: Gmail, Calendar, Drive, Sheets, Docs, and Tasks as a curated set of 41 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 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)

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

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
• 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_thread

... View full README on GitHub