Google Workspace MCP Server

Common errors

• GOOGLE_CLIENT_ID environment variable is required

  cause The server cannot find the necessary Google OAuth Client ID to initiate authentication.
  fix Set the `GOOGLE_OAUTH_CLIENT_ID` environment variable in your shell or configuration file. For example: `export GOOGLE_OAUTH_CLIENT_ID="your-client-id.apps.googleusercontent.com"`.

• Invalid OAuth credentials

  cause The provided Google OAuth Client ID or Secret is incorrect, or the Google Cloud Project setup is incomplete.
  fix Verify that your `GOOGLE_OAUTH_CLIENT_ID` and `GOOGLE_OAUTH_CLIENT_SECRET` environment variables are correct. Ensure all required Google Workspace APIs are enabled in your Google Cloud Project, and that your OAuth consent screen includes you as a test user if the app is in 'Testing' status.

• Token refresh failed

  cause The cached OAuth token is invalid or expired, often due to app being in 'Testing' mode or a scope change.
  fix Remove the stored token files (e.g., `~/.mcp/google-workspace-mcp/` or `~/.config/google-workspace-mcp/tokens.json`) to force re-authentication. If tokens expire frequently, ensure your OAuth app is published to 'In production' status.

• API not enabled

  cause A Google Workspace API required by a tool (e.g., Gmail API, Drive API) has not been enabled in your Google Cloud Project.
  fix Go to the Google Cloud Console, navigate to 'APIs & Services' > 'Library', and enable the specific API mentioned in the error message.

Warnings

• gotcha Using 'Domain-Wide Delegation (DWD) enabled service accounts' ('Scary Mode' from v1.18.0) has significant security implications. Only use if you fully understand the risks and have robust controls in place.
  Fix: Avoid DWD unless absolutely necessary. For typical use, prefer standard OAuth 2.0 'Desktop application' or 'Web application' credentials and manage scopes carefully.
• gotcha The type of Google OAuth client ID (Desktop vs. Web application) must match your deployment. 'Desktop application' is for local CLI/stdio, while 'Web application' is for hosted HTTP deployments, reverse proxies, and browser-based clients. Using the wrong type can lead to authentication failures.
  Fix: Ensure your Google Cloud OAuth 2.0 Client ID is created as a 'Desktop application' for local use, or 'Web application' with correctly configured Authorized JavaScript origins and Redirect URIs for hosted environments.
• gotcha OAuth tokens for applications in 'Testing' status on Google Cloud expire after 7 days, requiring frequent re-authentication. This can be disruptive during development.
  Fix: To avoid weekly token expiry, ensure your OAuth consent screen is published to 'In production' status.
• breaking Version 1.17.3 introduced a fix for credential file permissions (0600) and path traversal sanitization. Older versions might have been vulnerable to insecure file permissions or path traversal attacks related to credential files.
  Fix: Upgrade to v1.17.3 or later to ensure credential file security. Review existing credential file permissions if running older versions.
• gotcha When setting up Google Custom Search (PSE), you must create a Search Engine ID in the Custom Search Control Panel and enable the 'Custom Search API' in your Google Cloud Project, also requiring an API key. This is a separate credential setup from general Workspace APIs.
  Fix: Follow the specific instructions for Custom Search Engine setup in the documentation, including obtaining a Search Engine ID and a restricted API key for the Custom Search API.

Install

• pip install workspace-mcp Standard pip installation
• uvx workspace-mcp Instant run CLI (requires 'uv' installed)

Imports

• FastMCP

  from fastmcp import FastMCP

  Used when defining a custom MCP server or extending `workspace-mcp` with new tools.
• require_google_service

  from auth.service_decorator import require_google_service

  Decorator used to define tools that require specific Google Workspace service access and OAuth scopes.

Quickstart

This quickstart demonstrates how to set up environment variables for Google OAuth and then start the `workspace-mcp` server using the `uvx` CLI tool. It requires a Google Cloud Project with OAuth 2.0 credentials configured for a 'Desktop application' and the necessary Workspace APIs enabled. The server will run and expose Google Workspace tools to compatible MCP clients.

import os
import subprocess

# --- Step 1: Set up Google OAuth Credentials ---
# Create a Google Cloud Project, enable necessary APIs (e.g., Gmail API, Google Calendar API, Google Drive API).
# Configure the OAuth consent screen (External, add yourself as test user, add scopes).
# Create OAuth 2.0 credentials: Choose 'Desktop application' type.
# Note your Client ID and Client Secret. Set them as environment variables.
# For a web application, ensure redirect URIs and origins match your deployment.

# Replace with your actual Google OAuth Client ID and Secret
os.environ['GOOGLE_OAUTH_CLIENT_ID'] = os.environ.get('GOOGLE_OAUTH_CLIENT_ID', 'YOUR_GOOGLE_CLIENT_ID')
os.environ['GOOGLE_OAUTH_CLIENT_SECRET'] = os.environ.get('GOOGLE_OAUTH_CLIENT_SECRET', 'YOUR_GOOGLE_CLIENT_SECRET')

# Optional: For local legacy HTTP callback flows, may be required for certain setups.
# os.environ['OAUTHLIB_INSECURE_TRANSPORT'] = '1'

# --- Step 2: Start the Google Workspace MCP Server ---
# 'uvx' is recommended for instant run. Ensure 'uv' is installed (`pip install uv`).
# '--transport streamable-http' is recommended for modern MCP clients.
# '--tool-tier core' or explicit '--tools gmail drive calendar' selects services.

print("Starting Google Workspace MCP Server...")
try:
    subprocess.run(
        ["uvx", "workspace-mcp", "--transport", "streamable-http", "--tool-tier", "core"],
        check=True
    )
except FileNotFoundError:
    print("Error: 'uvx' command not found. Please install 'uv' with `pip install uv`.")
except subprocess.CalledProcessError as e:
    print(f"Server exited with an error: {e}")

print("Server stopped.")