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 USER_GOOGLE_EMAIL=your.email@gmail.com # 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.