google-workspace-mcp-advanced 1.0.1

Advanced Google Workspace MCP Server - Gmail, Calendar, Drive, Docs, Sheets, Slides, Forms, Tasks, Chat, Search with bidirectional sync

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

• 10 service domains: Gmail, Drive, Calendar, Docs, Sheets, Chat, Forms, Slides, Tasks, Search
• 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

# 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.1 --transport stdio

3. Add MCP client config

{
  "mcpServers": {
    "google-workspace": {
      "command": "uvx",
      "args": ["google-workspace-mcp-advanced==1.0.1", "--transport", "stdio"],
      "env": {
        "USER_GOOGLE_EMAIL": "[e-mail]"
      }
    }
  }
}

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.
4. In streamable-http, complete callback auth by opening the OAuth URL shown by the server.
5. Credentials are saved in ~/.config/gws-mcp-advanced/credentials/.

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": "[e-mail]"
      }
    }
  }
}

Service Coverage

Service	Example Capabilities
Gmail	search, read, draft, send, labels, filters
Drive	search, read, upload, permissions, ownership transfer
Calendar	list/create/modify/delete events
Docs	create/update docs, markdown insertion, table and image handling
Sheets	read/write ranges, formatting, conditional formatting
Chat	list spaces, read/send messages
Forms	create forms, read responses, update publish settings
Slides	create presentations, batch updates
Tasks	task lists and task lifecycle management
Search	programmable search endpoint support

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

Variable	Required	Description
USER_GOOGLE_EMAIL	Yes	Target Google account email
GOOGLE_OAUTH_CLIENT_ID	Yes	OAuth client ID
GOOGLE_OAUTH_CLIENT_SECRET	Yes	OAuth client secret
WORKSPACE_MCP_CONFIG_DIR	No	Config/credential directory override
WORKSPACE_MCP_AUTH_FLOW	No	Auth interaction mode: auto (default), device, or callback

Documentation

• User docs: docs/INDEX.md
• Client setup hub: docs/setup/MCP_CLIENT_SETUP_GUIDE.md
• Authentication model: docs/setup/AUTHENTICATION_MODEL.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
• Distribution/release guide: docs/DISTRIBUTION_RELEASE.md
• Comparison with upstream: docs/COMPARISON.md

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