Google Workspace MCP Advanced

Production-ready MCP server for Google Workspace.

google-workspace-mcp-advanced gives MCP clients broad Google Workspace coverage with safe-by-default write operations, Markdown-to-Google-Docs support, and Drive sync workflows.

Why This Project

• 11 service domains: Gmail, Drive, Calendar, Docs, Sheets, Chat, Forms, Slides, Tasks, Search, Apps Script
• 100+ tools for read and write operations
• Dry-run defaults for mutating operations
• Strong Markdown rendering for Google Docs (kitchen-sink validated)
• Persistent OAuth sessions and resilient auth storage

Quick Start

1. Install uv

# macOS (Homebrew)
brew install uv

# Windows (winget)
winget install --id=astral-sh.uv -e

# Windows (PowerShell installer)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Linux/macOS (official installer)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Verify
uv --version

2. Run the MCP server from PyPI (recommended)

# Stable channel (latest release)
uvx google-workspace-mcp-advanced --transport stdio

# Pinned deterministic version (recommended for teams)
uvx google-workspace-mcp-advanced==1.0.10 --transport stdio

3. Add MCP client config

{
  "mcpServers": {
    "google-workspace": {
      "command": "uvx",
      "args": ["google-workspace-mcp-advanced==1.0.10", "--transport", "stdio"],
      "env": {
        "USER_GOOGLE_EMAIL": "your.email@company.com"
      }
    }
  }
}

4. Use client-specific setup guides

• Claude Code MCP setup
• Cursor MCP setup
• OpenCode MCP setup
• Gemini CLI MCP setup

5. Authenticate on first run

1. Start the server from your MCP client.
2. Run any Google tool (for example, list calendars or list Drive files).
3. In stdio mode (default), complete the device flow:
   • open the verification URL,
   • enter the user code,
   • retry your tool call.
   • if device flow is unsupported for your OAuth client type, the server falls back to callback flow automatically.
4. In streamable-http, complete callback auth by opening the OAuth URL shown by the server.
   • for MCP-hosted/manual completion workflows, use complete_google_auth with the browser callback URL.
5. Credentials are saved in ~/.config/google-workspace-mcp-advanced/credentials/.
6. Legacy directory ~/.config/gws-mcp-advanced/ is still supported for migration.

Single-MCP Multi-Client Mode

Use one MCP entry with multiple OAuth clients (for example private + enterprise tenants) via:

• auth_clients.json under WORKSPACE_MCP_CONFIG_DIR
• deterministic routing by script_clients, account_clients, and domain_clients
• setup tools: setup_google_auth_clients, import_google_auth_client
• completion tool: complete_google_auth

Guide:

• Single-MCP Multi-Client Auth Setup

Local Development Mode

Use repository-local execution when building or testing unreleased changes.

{
  "mcpServers": {
    "google-workspace-dev": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "/path/to/google-workspace-mcp-advanced",
        "google-workspace-mcp-advanced",
        "--transport",
        "stdio"
      ],
      "env": {
        "USER_GOOGLE_EMAIL": "your.email@company.com"
      }
    }
  }
}

Service Coverage

Safety Model

• Mutating tools default to dry_run=True.
• You must pass dry_run=False to execute real changes.
• This reduces accidental writes during assistant experimentation.

Common Runtime Commands

# Run locally from repo
uv run google-workspace-mcp-advanced --transport stdio

# HTTP transport
uv run google-workspace-mcp-advanced --transport streamable-http

# Single-user mode
uv run google-workspace-mcp-advanced --single-user

# Load specific service groups only
uv run google-workspace-mcp-advanced --tools gmail drive calendar

Required Environment Variables

Migration from Legacy Name

If you previously ran the project as gws-mcp-advanced, follow:

• Migration Guide (legacy name/path to current)

Documentation

• User docs: docs/INDEX.md
• Client setup hub: docs/setup/MCP_CLIENT_SETUP_GUIDE.md
• Migration guide: docs/setup/MIGRATING_FROM_GWS_MCP_ADVANCED.md
• Authentication model: docs/setup/AUTHENTICATION_MODEL.md
• Single-MCP multi-client auth setup: docs/setup/MULTI_CLIENT_AUTH_SETUP.md
• Apps Script setup and limitations: docs/setup/APPS_SCRIPT_SETUP.md
• Apps Script capabilities and workflows: docs/setup/APPS_SCRIPT_USER_GUIDE.md
• Apps Script + clasp workflows: docs/setup/APPS_SCRIPT_CLASP_GUIDE.md
• Claude Code setup: docs/setup/CLAUDE_CODE_MCP_SETUP.md
• Cursor setup: docs/setup/CURSOR_MCP_SETUP.md
• OpenCode setup: docs/setup/OPENCODE_MCP_SETUP.md
• Gemini CLI setup: docs/setup/GEMINI_CLI_MCP_SETUP.md
• Cadence workflow user guide: docs/setup/LIVE_CADENCE_WORKFLOW.md
• Distribution/release guide: docs/DISTRIBUTION_RELEASE.md
• Release notes: docs/RELEASE_NOTES.md
• Comparison with upstream: docs/COMPARISON.md

Contributor docs live in AGENTS.md and agent-docs/.