See it in action:

A production-ready MCP server that integrates all major Google Workspace services with AI assistants. Built with FastMCP for optimal performance, featuring advanced authentication handling, service caching, and streamlined development patterns.

• 🔐 Advanced OAuth 2.0: Secure authentication with automatic token refresh, transport-aware callback handling, session management, and centralized scope management
• 📅 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
• 🔄 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.

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

# Requires Python 3.11+ 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.

# 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.11+ 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

• Python 3.11+
• 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

   • Enable APIs: Calendar, Drive, Gmail, Docs, Sheets, Slides, Forms, Tasks, Chat

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

   • 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="https://localhost:8000/oauth2callback"  # Optional

     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

   Credential Loading Priority:

   1. Environment variables (GOOGLE_OAUTH_CLIENT_ID, GOOGLE_OAUTH_CLIENT_SECRET)
   2. File specified by GOOGLE_CLIENT_SECRET_PATH or GOOGLE_CLIENT_SECRETS environment variable
   3. Default file (client_secret.json in 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

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: https://localhost). This affects the server_url used to construct the default OAUTH_REDIRECT_URI if GOOGLE_OAUTH_REDIRECT_URI is not set.
   • WORKSPACE_MCP_PORT: Sets the port the server listens on (default: 8000). This affects the server_url, port, and OAUTH_REDIRECT_URI.
   • 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.
   • GOOGLE_OAUTH_REDIRECT_URI: Sets an override for OAuth redirect specifically, must include a full address (i.e. include port if necessary). Use this if you want to run your OAuth redirect separately from the MCP. This is not recommended outside of very specific cases

# 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

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"
         }
       }
     }
   }

Get Google OAuth Credentials (if you don't have them):

• Go to Google Cloud Console
• Create a new project and enable APIs: Calendar, Drive, Gmail, Docs, Sheets, Slides, Forms, Tasks, Chat
• Create OAuth 2.0 Client ID (Web application) with redirect URI: https://localhost:8000/oauth2callback

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", "https://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 https://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 https://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:

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": "https://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: https://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.