Install and Pick Your Tools

One uvx command downloads and runs the server — no clone, no config files. Start with the core tier and widen scope only when a workflow needs it.

# Recommended: start with the core tier
uvx workspace-mcp --tool-tier core

# Or cherry-pick services
uvx workspace-mcp --tools gmail drive calendar tasks

# Step up when you need more
uvx workspace-mcp --tool-tier extended
uvx workspace-mcp --tool-tier complete

Core Search, read, create, and basic modify across every service. Minimal API quota.

Extended Core plus management: labels, folders, batch operations, advanced search.

Complete Full API surface — comments, publishing settings, administrative functions.

Tiers are cumulative — each one includes everything below it.
Combine --tool-tier with --tools to apply a tier to just the services you list.

Requires Python 3.10+ and uv. uvx fetches the latest release on first run.

Create Your Google OAuth Client

Every setup needs an OAuth client from Google Cloud Console. Pick the client type that matches how you run the server, then export the credentials.

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

# Public OAuth 2.1 (PKCE) clients: omit the secret, set a signing key
export FASTMCP_SERVER_AUTH_GOOGLE_JWT_SIGNING_KEY="$(openssl rand -hex 32)"

# Local development over http:// only
export OAUTHLIB_INSECURE_TRANSPORT=1

Desktop application — local CLI and stdio setups, and public PKCE clients (no redirect URIs to manage).
Web application — hosted HTTP deployments, reverse proxies, and browser-based clients such as Open WebUI.
For Web application clients, authorized 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.

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

Google Cloud Console →Web Application Example →

Start the Server

Use streamable HTTP for modern clients, and enable OAuth 2.1 for multi-user deployments. Keep stdio only as a legacy fallback.

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

# Multi-user OAuth 2.1
export MCP_ENABLE_OAUTH21=true
uvx workspace-mcp --transport streamable-http --tool-tier core

# Legacy fallback (stdio)
uvx workspace-mcp --tool-tier core

OAuth 2.1 requires HTTP transport and cannot be combined with --single-user. The server listens at http://localhost:8000/mcp by default.

Connect Your MCP Client

Claude Desktop uses the custom connector flow. Claude Code and VS Code point at the HTTP endpoint directly.

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

# VS Code — add to .vscode/mcp.json or user mcp.json
{
  "servers": {
    "workspacemcp": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

Claude Desktop, web, and Cowork: Settings → Connectors → Add custom connector, then paste your server URL. The connector guide has step-by-step screenshots.
Claude Code: run the claude mcp add command above.
VS Code: add the server block to .vscode/mcp.json or your user mcp.json.
A .mcpb bundle on GitHub releases is an alternative for Claude Desktop, but the connector flow is the recommended path.

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

Claude Connector Guide →GitHub Releases →

Verify with workspace-cli

workspace-cli lists tools and calls them against your running server, with encrypted on-disk token caching — authenticate in the browser once and later calls reuse the session.

# List every registered tool
workspace-cli list

# Smoke-test a real tool call
workspace-cli call search_gmail_messages query="is:unread" max_results=5

# Target a remote endpoint
workspace-cli --url https://your-server/mcp list

Install it globally from the repo with uv tool install . — don't use uvx here; an abandoned PyPI package shares the name.
Confirm browser OAuth completes on the first authenticated call.
Confirm the tool list matches your --tool-tier or --tools selection.
Re-run after changing --read-only or --permissions to verify the registered tools changed.

Tokens are stored encrypted under ~/.workspace-mcp/cli-tokens/, so you only authenticate once.