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

For Claude Desktop, use the custom connector flow. For Claude Code and VS Code, configure the HTTP endpoint directly.

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

# VS Code — add to .vscode/mcp.json or user mcp.json
{
  "servers": {
    "workspace": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}
  • Claude Desktop / web / cowork: use Connectors → Add custom connector → paste your MCP server URL. See the FAQ for step-by-step screenshots.
  • Claude Code: run the `claude mcp add` command above.
  • VS Code: add the server block to your MCP config.
  • A `.mcpb` bundle is also available from GitHub releases as an alternative for Claude Desktop, but the connector flow is the recommended path.
Connector Setup (FAQ) →GitHub Releases →

The bundled Claude skill for Workspace tool routing is optional — install it from the repo if you want routing hints in Claude Code.

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`)