Quick Start Guide

Get started with Google Workspace MCP in 5 steps, from install and auth to transport setup and validation.

1

Install and Choose Tool Scope

Install with `uvx` and start with a tool tier (recommended) or explicit service list.

# Start with the recommended core tier
uvx workspace-mcp --tool-tier core

# Or choose explicit services
uvx workspace-mcp --tools gmail drive calendar tasks

# Expand when needed
uvx workspace-mcp --tool-tier extended
uvx workspace-mcp --tool-tier complete

Requires Python 3.10+ and uv/uvx.

2

Create Your Google OAuth Client

Every Workspace MCP setup needs a Google OAuth client ID and secret. Use the client type that matches how you run the server.

export GOOGLE_OAUTH_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export GOOGLE_OAUTH_CLIENT_SECRET="your-client-secret"

# Optional (local legacy HTTP callback only)
export OAUTHLIB_INSECURE_TRANSPORT=1
  • Use `Desktop application` for local CLI and stdio-based setups.
  • Use `Web application` for hosted HTTP deployments, reverse proxies, and browser-based clients such as Open WebUI.
  • For `Web application` clients, your Google Cloud origins and redirect URIs must match the public URL users authenticate against.
Example Google Cloud OAuth web application client configuration showing a Workspace MCP subdomain origin and localhost:8000 as an additional browser origin
Example Web Application client configuration. For cloud-only setups, use your hosted origin and matching `/oauth2callback` redirect URI. Add `http://localhost:8000` only if you are also testing a local browser client.
Google Cloud Console →Web Application Example →

Desktop clients do not require manual redirect URI setup for standard local flows. Web Application clients do.

3

Start the Server

Use streamable HTTP for modern clients and OAuth 2.1. Keep stdio only as a legacy fallback.

# Recommended for modern MCP clients
uvx workspace-mcp --transport streamable-http

# Enable OAuth 2.1 multi-user mode
export MCP_ENABLE_OAUTH21=true
uvx workspace-mcp --transport streamable-http

# Legacy fallback (stdio)
uvx workspace-mcp

OAuth 2.1 (`MCP_ENABLE_OAUTH21=true`) cannot be combined with `--single-user`.

4

Connect Your MCP Client

Use one-click DXT for Claude Desktop, or configure HTTP clients manually (Claude Code / VS Code).

# Claude Code (recommended)
claude mcp add --transport http workspace-mcp http://localhost:8000/mcp

# Optional: manual Claude Desktop stdio fallback
{
  "mcpServers": {
    "google_workspace": {
      "command": "uvx",
      "args": ["workspace-mcp"]
    }
  }
}
DXT Releases →

For Claude Desktop, prefer the one-click `.dxt` release installer when possible.

5

Verify with CLI and Tool Calls

Validate installation, auth flow, and tool availability with CLI checks.

# List tools
workspace-mcp --cli list --json

# Smoke test a real tool
workspace-mcp --cli search_gmail_messages --args '{"query": "is:unread", "max_results": 5}'
  • Confirm browser OAuth completes on first authenticated call
  • Confirm expected tool groups appear based on `--tool-tier` or `--tools`
  • If using OAuth 2.1, verify requests run over HTTP transport with bearer auth
  • Re-run checks after changing permissions (`--read-only` or `--permissions`)