See it in action:

A production-ready MCP server that integrates all major Google Workspace services with AI assistants. It supports both single-user operation and multi-user authentication via OAuth 2.1, making it a powerful backend for custom applications. Built with FastMCP for optimal performance, featuring advanced authentication handling, service caching, and streamlined development patterns.

• 🔐 Advanced OAuth 2.0 & OAuth 2.1: Secure authentication with automatic token refresh, transport-aware callback handling, session management, centralized scope management, and OAuth 2.1 bearer token support for multi-user environments with innovative CORS proxy architecture
• 📅 Google Calendar: Full calendar management with event CRUD operations
• 📁 Google Drive: File operations with native Microsoft Office format support (.docx, .xlsx)
• 📧 Gmail: Complete email management with search, send, and draft capabilities
• 📄 Google Docs: Document operations including content extraction, creation, and comment management
• 📊 Google Sheets: Comprehensive spreadsheet management with flexible cell operations and comment management
• 🖼️ Google Slides: Presentation management with slide creation, updates, content manipulation, and comment management
• 📝 Google Forms: Form creation, retrieval, publish settings, and response management
• ✓ Google Tasks: Complete task and task list management with hierarchy, due dates, and status tracking
• 💬 Google Chat: Space management and messaging capabilities
• 🔍 Google Custom Search: Programmable Search Engine (PSE) integration for custom web searches
• 🔄 All Transports: Stdio, Streamable HTTP & SSE, OpenAPI compatibility via mcpo
• ⚡ High Performance: Service caching, thread-safe sessions, FastMCP integration
• 🧩 Developer Friendly: Minimal boilerplate, automatic service injection, centralized configuration

1. Download: Grab the latest google_workspace_mcp.dxt from the “Releases” page
2. Install: Double-click the file – Claude Desktop opens and prompts you to Install
3. Configure: In Claude Desktop → Settings → Extensions → Google Workspace MCP, paste your Google OAuth credentials
4. Use it: Start a new Claude chat and call any Google Workspace tool

Why DXT?

Desktop Extensions (.dxt) bundle the server, dependencies, and manifest so users go from download → working MCP in one click – no terminal, no JSON editing, no version conflicts.

• Python 3.10+
• uvx (for instant installation) or uv (for development)
• Google Cloud Project with OAuth 2.0 credentials

1. Google Cloud Setup:

   • Create OAuth 2.0 credentials (web application) in Google Cloud Console

   • Create a new project (or use an existing one) for your MCP server.

   • Navigate to APIs & Services → Credentials.

   • Click Create Credentials → OAuth Client ID.

   • Choose Web Application as the application type.

   • Add redirect URI: http://localhost:8000/oauth2callback

   • Enable APIs:

   • In the Google Cloud Console, go to APIs & Services → Library.

   • Search for & enable Calendar, Drive, Gmail, Docs, Sheets, Slides, Forms, Tasks, Chat

   • Expand the section below marked "API Enablement Links" for direct links to each!

1.1. Credentials:

• Configure credentials using one of these methods:

  Option A: Environment Variables (Recommended for Production)

  export GOOGLE_OAUTH_CLIENT_ID="your-client-id.apps.googleusercontent.com"
  export GOOGLE_OAUTH_CLIENT_SECRET="your-client-secret"
  export GOOGLE_OAUTH_REDIRECT_URI="http://localhost:8000/oauth2callback"  # Optional - see Reverse Proxy Setup below

  Option B: File-based (Traditional)

  • Download credentials as client_secret.json in project root
  • To use a different location, set GOOGLE_CLIENT_SECRET_PATH (or legacy GOOGLE_CLIENT_SECRETS) environment variable with the file path

  Option C: .env File (Recommended for Development)

  • Copy the provided .env.oauth21 example file to .env in the project root:

  cp .env.oauth21 .env

  • Edit the .env file to add your GOOGLE_OAUTH_CLIENT_ID and GOOGLE_OAUTH_CLIENT_SECRET.
  • The server automatically loads variables from this file on startup, simplifying local development.

Credential Loading Priority: The server loads credentials in the following order of precedence:

1. Manually set environment variables (e.g., export VAR=value).
2. Variables defined in a .env file in the project root.
3. client_secret.json file specified by GOOGLE_CLIENT_SECRET_PATH.
4. Default client_secret.json file in the project root.

Why Environment Variables?

• ✅ Containerized deployments (Docker, Kubernetes)
• ✅ Cloud platforms (Heroku, Railway, etc.)
• ✅ CI/CD pipelines
• ✅ No secrets in version control
• ✅ Easy credential rotation

2. Environment:

   export OAUTHLIB_INSECURE_TRANSPORT=1  # Development only
   export [email protected]  # Optional: Default email for auth - use this for single user setups and you won't need to set your email in system prompt for magic auth
   export GOOGLE_PSE_API_KEY=your-custom-search-api-key  # Optional: Only needed for Google Custom Search tools
   export GOOGLE_PSE_ENGINE_ID=your-search-engine-id  # Optional: Only needed for Google Custom Search tools

3. Server Configuration: The server's base URL and port can be customized using environment variables:

   • WORKSPACE_MCP_BASE_URI: Sets the base URI for the server (default: http://localhost). Note: do not include a port in WORKSPACE_MCP_BASE_URI - set that with the variable below.
   • WORKSPACE_MCP_PORT: Sets the port the server listens on (default: 8000).
   • GOOGLE_OAUTH_REDIRECT_URI: Override the OAuth redirect URI (useful for reverse proxy setups - see below).
   • USER_GOOGLE_EMAIL: Optional default email for authentication flows. If set, the LLM won't need to specify your email when calling start_google_auth.

To use the Google Custom Search tools, you need to:

1. Create a Programmable Search Engine:

   • Go to Programmable Search Engine Control Panel
   • Configure sites to search (or search the entire web)
   • Note your Search Engine ID (cx parameter)

2. Get an API Key:

   • Visit Google Developers Console
   • Create or select a project
   • Enable the Custom Search API
   • Create credentials (API Key)
   • Set the GOOGLE_PSE_API_KEY environment variable with your API key

3. Configure Environment Variables:

   • Set GOOGLE_PSE_API_KEY to your Custom Search API key
   • Set GOOGLE_PSE_ENGINE_ID to your Search Engine ID (the cx parameter from step 1)

For detailed setup instructions, see the Custom Search JSON API documentation.

# Default (stdio mode for MCP clients)
uv run main.py

# HTTP mode (for web interfaces and debugging)
uv run main.py --transport streamable-http

# Single-user mode (simplified authentication)
uv run main.py --single-user

# Selective tool registration (only register specific tools)
uv run main.py --tools gmail drive calendar tasks
uv run main.py --tools sheets docs
uv run main.py --single-user --tools gmail  # Can combine with other flags

# Docker
docker build -t workspace-mcp .
docker run -p 8000:8000 -v $(pwd):/app workspace-mcp --transport streamable-http

Available Tools for --tools flag: gmail, drive, calendar, docs, sheets, forms, tasks, chat, search

The server includes OAuth 2.1 support for bearer token authentication, enabling multi-user session management. OAuth 2.1 automatically reuses your existing GOOGLE_OAUTH_CLIENT_ID and GOOGLE_OAUTH_CLIENT_SECRET credentials - no additional configuration needed!

When to use OAuth 2.1:

• Multiple users accessing the same MCP server instance
• Need for bearer token authentication instead of passing user emails
• Building web applications or APIs on top of the MCP server
• Production environments requiring secure session management
• Browser-based clients requiring CORS support

Enabling OAuth 2.1: To enable OAuth 2.1, set the MCP_ENABLE_OAUTH21 environment variable to true.

# OAuth 2.1 requires HTTP transport mode
export MCP_ENABLE_OAUTH21=true
uv run main.py --transport streamable-http

If MCP_ENABLE_OAUTH21 is not set to true, the server will use legacy authentication, which is suitable for clients that do not support OAuth 2.1.

The server supports two transport modes:

Guided Setup (Recommended if not using DXT)

python install_claude.py

This script automatically:

• Prompts you for your Google OAuth credentials (Client ID and Secret)
• Creates the Claude Desktop config file in the correct location
• Sets up all necessary environment variables
• No manual file editing required!

After running the script, just restart Claude Desktop and you're ready to go.

Manual Claude Configuration (Alternative)

1. Open Claude Desktop Settings → Developer → Edit Config
   1. macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   2. Windows: %APPDATA%\Claude\claude_desktop_config.json
2. Add the server configuration:

   {
     "mcpServers": {
       "google_workspace": {
         "command": "uvx",
         "args": ["workspace-mcp"],
         "env": {
           "GOOGLE_OAUTH_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
           "GOOGLE_OAUTH_CLIENT_SECRET": "your-client-secret",
           "OAUTHLIB_INSECURE_TRANSPORT": "1"
         }
       }
     }
   }

If you’re developing, deploying to servers, or using another MCP-capable client, keep reading.

# Requires Python 3.10+ and uvx
export GOOGLE_OAUTH_CLIENT_ID="xxx"
export GOOGLE_OAUTH_CLIENT_SECRET="yyy"
uvx workspace-mcp --tools gmail drive calendar

Run instantly without manual installation - you must configure OAuth credentials when using uvx. You can use either environment variables (recommended for production) or set the GOOGLE_CLIENT_SECRET_PATH (or legacy GOOGLE_CLIENT_SECRETS) environment variable to point to your client_secret.json file.

If you're running the MCP server behind a reverse proxy (nginx, Apache, Cloudflare, etc.), you'll need to configure GOOGLE_OAUTH_REDIRECT_URI to match your external URL:

Problem: When behind a reverse proxy, the server constructs redirect URIs using internal ports (e.g., http://localhost:8000/oauth2callback) but Google expects the external URL (e.g., https://your-domain.com/oauth2callback).

Solution: Set GOOGLE_OAUTH_REDIRECT_URI to your external URL:

# External URL without port (nginx/Apache handling HTTPS)
export GOOGLE_OAUTH_REDIRECT_URI="https://your-domain.com/oauth2callback"

# Or with custom port if needed
export GOOGLE_OAUTH_REDIRECT_URI="https://your-domain.com:8443/oauth2callback"

Important:

• The redirect URI must exactly match what's configured in your Google Cloud Console
• The server will use this value for all OAuth flows instead of constructing it from WORKSPACE_MCP_BASE_URI and WORKSPACE_MCP_PORT
• Your reverse proxy must forward /oauth2callback requests to the MCP server

# Set OAuth credentials via environment variables (recommended)
export GOOGLE_OAUTH_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export GOOGLE_OAUTH_CLIENT_SECRET="your-client-secret"

# Start the server with all Google Workspace tools
uvx workspace-mcp

# Start with specific tools only
uvx workspace-mcp --tools gmail drive calendar tasks

# Start in HTTP mode for debugging
uvx workspace-mcp --transport streamable-http

Requires Python 3.10+ and uvx. The package is available on PyPI.

For development or customization:

git clone https://github.com/taylorwilsdon/google_workspace_mcp.git
cd google_workspace_mcp
uv run main.py

Development Installation (For Contributors):

{
  "mcpServers": {
    "google_workspace": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/repo/google_workspace_mcp",
        "main.py"
      ],
      "env": {
        "GOOGLE_OAUTH_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_OAUTH_CLIENT_SECRET": "your-client-secret",
        "OAUTHLIB_INSECURE_TRANSPORT": "1"
      }
    }
  }
}

If you need to use HTTP mode with Claude Desktop:

{
  "mcpServers": {
    "google_workspace": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:8000/mcp"]
    }
  }
}

Note: Make sure to start the server with --transport streamable-http when using HTTP mode.

The server features transport-aware OAuth callback handling:

• Stdio Mode: Automatically starts a minimal HTTP server on port 8000 for OAuth callbacks
• HTTP Mode: Uses the existing FastAPI server for OAuth callbacks
• Same OAuth Flow: Both modes use http://localhost:8000/oauth2callback for consistency

When calling a tool:

1. Server returns authorization URL
2. Open URL in browser and authorize
3. Server handles OAuth callback automatically (on port 8000 in both modes)
4. Retry the original request

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

google_workspace_mcp/
├── auth/              # Authentication system with decorators
├── core/              # MCP server and utilities
├── g{service}/        # Service-specific tools
├── main.py            # Server entry point
├── client_secret.json # OAuth credentials (not committed)
└── pyproject.toml     # Dependencies

from auth.service_decorator import require_google_service

@require_google_service("drive", "drive_read")  # Service + scope group
async def your_new_tool(service, param1: str, param2: int = 10):
    """Tool description"""
    # service is automatically injected and cached
    result = service.files().list().execute()
    return result  # Return native Python objects

• Service Caching: 30-minute TTL reduces authentication overhead
• Scope Management: Centralized in SCOPE_GROUPS for easy maintenance
• Error Handling: Native exceptions instead of manual error construction
• Multi-Service Support: @require_multiple_services() for complex tools

• Credentials: Never commit client_secret.json or .credentials/ directory
• OAuth Callback: Uses http://localhost:8000/oauth2callback for development (requires OAUTHLIB_INSECURE_TRANSPORT=1)
• Transport-Aware Callbacks: Stdio mode starts a minimal HTTP server only for OAuth, ensuring callbacks work in all modes
• Production: Use HTTPS for callback URIs and configure accordingly
• Network Exposure: Consider authentication when using mcpo over networks
• Scope Minimization: Tools request only necessary permissions

To use this server as a tool provider within Open WebUI:

Just copy and paste the below, set your values and you're off!

GOOGLE_OAUTH_CLIENT_ID="your_client_id" GOOGLE_OAUTH_CLIENT_SECRET="your_client_secret" uvx mcpo --port 8000 --api-key "top-secret" -- uvx workspace-mcp

Otherwise:

Create a file named config.json with the following structure to have mcpo make the streamable HTTP endpoint available as an OpenAPI spec tool:

{
  "mcpServers": {
    "google_workspace": {
      "type": "streamablehttp",
      "url": "http://localhost:8000/mcp"
    }
  }
}

mcpo --port 8001 --config config.json --api-key "your-optional-secret-key"

This command starts the mcpo proxy, serving your active (assuming port 8000) Google Workspace MCP on port 8001.

1. Navigate to your Open WebUI settings
2. Go to "Connections" → "Tools"
3. Click "Add Tool"
4. Enter the Server URL: http://localhost:8001/google_workspace (matching the mcpo base URL and server name from config.json)
5. If you used an --api-key with mcpo, enter it as the API Key
6. Save the configuration

The Google Workspace tools should now be available when interacting with models in Open WebUI.

MIT License - see LICENSE file for details.