See it in action:

Overview

Workspace MCP is the single most complete MCP server, the only that integrates all major Google Workspace services with AI assistants and all agent platforms. The entire toolset is available for CLI usage supporting both local and remote instances.

Features

> 12 services  —  Gmail · Drive · Calendar · Docs · Sheets · Slides · Forms · Chat · Apps Script · Tasks · Contacts · Search

Security & Compliance

Quick Start

> Set credentials → pick a launch command → connect your client

# 1. Credentials
export GOOGLE_OAUTH_CLIENT_ID="..."
export GOOGLE_OAUTH_CLIENT_SECRET="..."

# 2. Launch — pick a tier
uvx workspace-mcp --tool-tier core       # essential tools
uvx workspace-mcp --tool-tier extended   # core + management ops
uvx workspace-mcp --tool-tier complete   # everything

# Or cherry-pick services
uv run main.py --tools gmail drive calendar

# 1. Credentials
export MCP_ENABLE_OAUTH21=true
export GOOGLE_OAUTH_CLIENT_ID="..."
export WORKSPACE_MCP_PORT=8000
export GOOGLE_OAUTH_REDIRECT_URI="http://localhost:${WORKSPACE_MCP_PORT}/oauth2callback"
export OAUTHLIB_INSECURE_TRANSPORT=1
# Leave GOOGLE_OAUTH_CLIENT_SECRET unset for public PKCE clients
export FASTMCP_SERVER_AUTH_GOOGLE_JWT_SIGNING_KEY="$(openssl rand -hex 32)"

# 2. Launch — OAuth 2.1 requires HTTP transport
uvx workspace-mcp --transport streamable-http --tool-tier core
uvx workspace-mcp --transport streamable-http --tool-tier extended
uvx workspace-mcp --transport streamable-http --tool-tier complete

# Or cherry-pick services
uv run main.py --transport streamable-http --tools gmail drive calendar

_{Credential setup → · All launch options → · Tier details →}

Quick Start — Connect Claude to Google Workspace

The recommended setup is to run an instance and connect Claude to it via a Connector. Full instructions at workspacemcp.com/quick-start.

Prerequisites

Python 3.10+ · uv/uvx · Google Cloud Project with OAuth 2.0 credentials

If you want the GCS credential store backend, install the optional dependency first:

uv sync --extra gcs
# or
pip install "workspace-mcp[gcs]"

Configuration

   export GOOGLE_OAUTH_CLIENT_ID="your-client-id"
   export GOOGLE_OAUTH_CLIENT_SECRET="your-secret"

pip install "workspace-mcp[otel]"
# Or, when installing from source: uv sync --extra otel

export OTEL_EXPORTER_OTLP_ENDPOINT="http://otel-collector:4317"
export OTEL_EXPORTER_OTLP_PROTOCOL="grpc"   # or "http/protobuf" (default: grpc)
export OTEL_SERVICE_NAME="google-workspace-mcp"   # optional; this is the default

Google Custom Search Setup

programmablesearchengine.google.com
/controlpanel/create

→ Configure sites or entire web
→ Note your Engine ID (cx)

developers.google.com
/custom-search/v1/overview

→ Create/select project
→ Enable Custom Search API
→ Create credentials (API Key)

export GOOGLE_PSE_API_KEY=
  "your-api-key"
export GOOGLE_PSE_ENGINE_ID=
  "your-engine-id"

   export GOOGLE_PSE_API_KEY="AIzaSy..."
   export GOOGLE_PSE_ENGINE_ID="01764344478..."

Start the Server

> 📌 Transport Mode Guidance: Use streamable HTTP mode (--transport streamable-http) for all modern MCP clients including Claude Code, VS Code MCP, and MCP Inspector. For Claude Desktop, run an instance and connect via a Connector. Stdio mode is a legacy fallback. For deployments, prefer OAuth 2.1 with stateless mode (MCP_ENABLE_OAUTH21=true, WORKSPACE_MCP_STATELESS_MODE=true) unless you need local attachment or credential storage.

> OAuth state safety: Legacy stdio starts a local-only OAuth callback server. In single-user mode only, it may recover a missing Google state parameter by consuming the most recent pending local OAuth state. This fallback is intentionally disabled outside single-user mode because it can cross session boundaries. Do not enable or emulate this behavior in streamable HTTP, hosted, or multi-user deployments; those modes must require an explicit state match.

uv run main.py

export MCP_ENABLE_OAUTH21=true
export GOOGLE_OAUTH_CLIENT_ID="..."
uv run main.py 
  --transport streamable-http

uv run main.py 
  --single-user

# Load specific services only
uv run main.py --tools gmail drive calendar
uv run main.py --tools sheets docs

# Combine with other flags
uv run main.py --single-user --tools gmail

# Requests only read-only scopes & disables write tools
uv run main.py --read-only

# Combine with specific tools or tiers
uv run main.py --tools gmail drive --read-only
uv run main.py --tool-tier core --read-only

# Per-service permission levels
uv run main.py --permissions gmail:organize drive:readonly

# Combine permissions with tier filtering
uv run main.py --permissions gmail:send drive:full --tool-tier core

# Optional bridge only for local legacy stdio sessions
WORKSPACE_MCP_HTTP_PORT=8001 uv run main.py
workspace-cli --url http://127.0.0.1:8001/mcp list

uv run main.py --tool-tier core      # ● Essential tools only
uv run main.py --tool-tier extended  # ◐ Core + additional
uv run main.py --tool-tier complete  # ○ All available tools

docker build -t workspace-mcp .
docker run -p 8000:8000 -v $(pwd):/app 
  -e MCP_ENABLE_OAUTH21=true 
  -e GOOGLE_OAUTH_CLIENT_ID="..." 
  workspace-mcp --transport streamable-http

# With tool selection via environment variables
docker run -e TOOL_TIER=core workspace-mcp
docker run -e TOOLS="gmail drive calendar" workspace-mcp

CLI

The workspace-cli command lists tools and calls them against a running server — with encrypted, disk-backed OAuth token caching so you only authenticate once. On first run it opens a browser for Google consent; subsequent runs reuse the cached tokens automatically.

Tokens are stored encrypted at ~/.workspace-mcp/cli-tokens/ using a Fernet key auto-generated at ~/.workspace-mcp/.cli-encryption-key.

To use workspace-cli globally, you'll want to start in this repo and run uv tool install .

Once complete, you'll have workspace-cli available globally via workspace-cli

Note: there is a public (but abandoned) pypi package with the same name - do not use uvx, as it will pull the wrong thing.

uv run workspace-cli list
uv run workspace-cli --url https://custom.server/mcp list

# Or, if installed globally:
workspace-cli list
workspace-cli --url https://custom.server/mcp list

uv run workspace-cli call search_gmail_messages 
  query="is:unread" max_results=5

fastmcp inspect fastmcp_server.py                        # print tools, resources, prompts
fastmcp install claude-code fastmcp_server.py             # one-command client setup
fastmcp install cursor fastmcp_server.py
fastmcp discover                                          # find servers configured in editors

Tool Tiers

The server organizes tools into three progressive tiers for simplified deployment. Choose a tier that matches your usage needs and API quota requirements.

Usage Examples

# Basic tier selection
uv run main.py --tool-tier core                            # Start with essential tools only
uv run main.py --tool-tier extended                        # Expand to include management features
uv run main.py --tool-tier complete                        # Enable all available functionality

# Selective service loading with tiers
uv run main.py --tools gmail drive --tool-tier core        # Core tools for specific services
uv run main.py --tools gmail --tool-tier extended          # Extended Gmail functionality only
uv run main.py --tools docs sheets --tool-tier complete    # Full access to Docs and Sheets

# Combine tier selection with granular permission levels
uv run main.py --permissions gmail:organize drive:full --tool-tier core

📋 Credential Configuration

export GOOGLE_OAUTH_CLIENT_ID=
  "your-client-id"
export GOOGLE_OAUTH_CLIENT_SECRET=
  "your-secret"

# Download & place in project root
client_secret.json

# Or specify custom path
export GOOGLE_CLIENT_SECRET_PATH=
  /path/to/secret.json

cp .env.oauth21 .env
# Edit .env with credentials

🧰 Available Tools

> Note: All tools support automatic authentication via @require_google_service() decorators with 30-minute service caching.

📅 Google Calendar _{<code class="ra0-md-code">calendar_tools.py</code>}

| _Tool | _Tier | _Description |
|------|------|-------------|
| _{list_calendars} | _Core | _{List accessible calendars} |
| _{get_events} | _Core | _{Retrieve events with time range filtering} |
| _{manage_event} | _Core | _{Create, update, or delete calendar events} |
| _{create_calendar} | _Extended | _{Create a new secondary Google Calendar} |
| _{query_freebusy} | _Extended | _{Query free/busy information for calendars} |
| _{manage_out_of_office} | _Extended | _{Create, list, update, or delete Out of Office events} |
| _{manage_focus_time} | _Extended | _{Create, list, update, or delete Focus Time events} |

📁 Google Drive _{<code class="ra0-md-code">drive_tools.py</code>}

| _Tool | _Tier | _Description |
|------|------|-------------|
| _{search_drive_files} | _Core | _{Search files with query syntax} |
| _{get_drive_file_content} | _Core | _{Read file content (Office, PDF, image)} |
| _{get_drive_file_download_url} | _Core | _{Download Drive files to local disk} |
| _{create_drive_file} | _Core | _{Create files or fetch from URLs} |
| _{create_drive_folder} | _Core | _{Create empty folders in Drive or shared drives} |
| _{import_to_google_doc} | _Core | _{Import files (MD, DOCX, HTML, etc.) as Google Docs} |
| _{import_to_google_slides} | _Core | _{Import presentation files (PPTX, PPT, ODP) as Google Slides} |
| _{import_to_google_sheets} | _Core | _{Import spreadsheet files (XLSX, CSV, TSV, etc.) as Google Sheets} |
| _{get_drive_shareable_link} | _Core | _{Get shareable links for a file} |
| _{list_drive_items} | _Extended | _{List folder contents or shared drives} |
| _{copy_drive_file} | _Extended | _{Copy existing files (templates) with optional renaming} |
| _{update_drive_file} | _Extended | _{Update metadata, move files, or replace Google Apps content} |
| _{manage_drive_access} | _Extended | _{Grant, update, revoke permissions, and transfer ownership} |
| _{set_drive_file_permissions} | _Extended | _{Set link sharing and file-level sharing settings} |
| _{get_drive_file_permissions} | _Complete | _{Get file metadata, parents, and permissions} |
| _{check_drive_file_public_access} | _Complete | _{Check public sharing status} |

📧 Gmail _{<code class="ra0-md-code">gmail_tools.py</code>}

| _Tool | _Tier | _Description |
|------|------|-------------|
| _{search_gmail_messages} | _Core | _{Search with Gmail operators} |
| _{get_gmail_message_content} | _Core | _{Retrieve message content (full=True returns the untruncated message via file/URL, or inline when no file storage)} |
| _{get_gmail_messages_content_batch} | _Core | _{Batch retrieve message content} |
| _{send_gmail_message} | _Core | _{Send emails} |
| _{get_gmail_thread_content} | _Extended | _{Get full thread content} |
| _{modify_gmail_message_labels} | _Extended | _{Modify message labels} |
| _{list_gmail_labels} | _Extended | _{List available labels} |
| _{list_gmail_filters} | _Extended | _{List Gmail filters} |
| _{manage_gmail_label} | _Extended | _{Create/update/delete labels} |
| _{manage_gmail_filter} | _Extended | _{Create or delete Gmail filters} |
| _{draft_gmail_message} | _Extended | _{Create drafts} |
| _{get_gmail_threads_content_batch} | _Complete | _{Batch retrieve thread content} |
| _{batch_modify_gmail_message_labels} | _Complete | _{Batch modify labels} |
| _{start_google_auth} | _Complete | _{Legacy OAuth 2.0 auth (disabled when OAuth 2.1 is enabled)} |

attachments=[{"path": "/path/to/report.pdf"}]

attachments=[{
    "filename": "report.pdf",
    "content": "JVBERi0xLjQK...",  # base64-encoded
    "mime_type": "application/pdf"   # optional
}]

export WORKSPACE_ATTACHMENT_DIR="/path/to/custom/dir"

📝 Google Docs _{<code class="ra0-md-code">docs_tools.py</code>}

| _Tool | _Tier | _Description |
|------|------|-------------|
| _{get_doc_content} | _Core | _{Extract document text} |
| _{create_doc} | _Core | _{Create new documents} |
| _{modify_doc_text} | _Core | _{Insert, replace, and richly format text with tab/segment targeting, append-to-segment support, advanced typography, and link management} |
| _{search_docs} | _Extended | _{Find documents by name} |
| _{find_and_replace_doc} | _Extended | _{Find and replace text} |
| _{list_docs_in_folder} | _Extended | _{List docs in folder} |
| _{insert_doc_elements} | _Extended | _{Add tables, lists, page breaks} |
| _{update_paragraph_style} | _Extended | _{Apply advanced paragraph styling including headings, spacing, direction, pagination controls, shading, and bulleted/numbered/checkbox lists with nesting} |
| _{get_doc_as_markdown} | _Extended | _{Export document as formatted Markdown with optional comments} |
| _{insert_doc_image} | _Complete | _{Insert images from Drive/URLs} |
| _{update_doc_headers_footers} | _Complete | _{Create or update headers and footers with correct segment-aware writes} |
| _{batch_update_doc} | _Complete | _{Execute atomic multi-step Docs API operations including named ranges, section breaks, document/section layout, header/footer creation, segment-aware inserts, images, tables, and rich formatting} |
| _{inspect_doc_structure} | _Complete | _{Analyze document structure, including safe insertion points, tables, section breaks, headers/footers, and named ranges} |
| _{export_doc_to_pdf} | _Extended | _{Export document to PDF} |
| _{create_table_with_data} | _Complete | _{Create data tables} |
| _{debug_table_structure} | _Complete | _{Debug table issues} |
| _{list_document_comments} | _Complete | _{List all document comments} |
| _{manage_document_comment} | _Complete | _{Create, reply to, or resolve comments} |
| _{manage_doc_tab} | _Complete | _{Create, rename, delete, or populate tabs from markdown} |

📊 Google Sheets _{<code class="ra0-md-code">sheets_tools.py</code>}

| _Tool | _Tier | _Description |
|------|------|-------------|
| _{read_sheet_values} | _Core | _{Read cell ranges} |
| _{modify_sheet_values} | _Core | _{Write/update/clear cells} |
| _{create_spreadsheet} | _Core | _{Create new spreadsheets} |
| _{list_spreadsheets} | _Extended | _{List accessible spreadsheets} |
| _{get_spreadsheet_info} | _Extended | _{Get spreadsheet metadata} |
| _{format_sheet_range} | _Extended | _{Apply colors, number formats, text wrapping, alignment, bold/italic, font size} |
| _{list_sheet_tables} | _Extended | _{List structured tables with IDs, names, ranges, and columns} |
| _{create_sheet} | _Complete | _{Add sheets to existing files} |
| _{move_sheet_rows} | _Complete | _{Move rows between sheets within a spreadsheet} |
| _{append_table_rows} | _Complete | _{Append rows to a structured table, auto-extending the table range} |
| _{list_spreadsheet_comments} | _Complete | _{List all spreadsheet comments} |
| _{manage_spreadsheet_comment} | _Complete | _{Create, reply to, or resolve comments} |
| _{manage_conditional_formatting} | _Complete | _{Add, update, or delete conditional formatting rules} |

🖼️ Google Slides _{<code class="ra0-md-code">slides_tools.py</code>}

| _Tool | _Tier | _Description |
|------|------|-------------|
| _{create_presentation} | _Core | _{Create new presentations} |
| _{get_presentation} | _Core | _{Retrieve presentation details} |
| _{batch_update_presentation} | _Extended | _{Apply multiple updates} |
| _{get_page} | _Extended | _{Get specific slide information} |
| _{get_page_thumbnail} | _Extended | _{Generate slide thumbnails} |
| _{list_presentation_comments} | _Complete | _{List all presentation comments} |
| _{manage_presentation_comment} | _Complete | _{Create, reply to, or resolve comments} |

📋 Google Forms _{<code class="ra0-md-code">forms_tools.py</code>}

| _Tool | _Tier | _Description |
|------|------|-------------|
| _{create_form} | _Core | _{Create new forms} |
| _{get_form} | _Core | _{Retrieve form details & URLs} |
| _{set_publish_settings} | _Complete | _{Configure form settings} |
| _{get_form_response} | _Complete | _{Get individual responses} |
| _{list_form_responses} | _Extended | _{List all responses with pagination} |
| _{batch_update_form} | _Complete | _{Apply batch updates (questions, settings)} |

✓ Google Tasks _{<code class="ra0-md-code">tasks_tools.py</code>}

| _Tool | _Tier | _Description |
|------|------|-------------|
| _{list_tasks} | _Core | _{List tasks with filtering} |
| _{get_task} | _Core | _{Retrieve task details} |
| _{manage_task} | _Core | _{Create, update, delete, or move tasks} |
| _{list_task_lists} | _Complete | _{List task lists} |
| _{get_task_list} | _Complete | _{Get task list details} |
| _{manage_task_list} | _Complete | _{Create, update, delete task lists, or clear completed tasks} |

👤 Google Contacts _{<code class="ra0-md-code">contacts_tools.py</code>}

| _Tool | _Tier | _Description |
|------|------|-------------|
| _{search_contacts} | _Core | _{Search contacts by name, email, phone} |
| _{get_contact} | _Core | _{Retrieve detailed contact info} |
| _{list_contacts} | _Core | _{List contacts with pagination} |
| _{manage_contact} | _Core | _{Create, update, or delete contacts} |
| _{list_contact_groups} | _Extended | _{List contact groups/labels} |
| _{get_contact_group} | _Extended | _{Get group details with members} |
| _{manage_contacts_batch} | _Complete | _{Batch create, update, or delete contacts} |
| _{manage_contact_group} | _Complete | _{Create, update, delete groups, or modify membership} |

💬 Google Chat _{<code class="ra0-md-code">chat_tools.py</code>}

| _Tool | _Tier | _Description |
|------|------|-------------|
| _{list_spaces} | _Extended | _{List chat spaces/rooms} |
| _{get_messages} | _Core | _{Retrieve space messages} |
| _{send_message} | _Core | _{Send messages to spaces} |
| _{search_messages} | _Core | _{Search across chat history} |
| _{create_reaction} | _Core | _{Add emoji reaction to a message} |
| _{download_chat_attachment} | _Extended | _{Download attachment from a chat message} |

Google Chat API is only available to Google Workspace users.