taylorwilsdon/google_workspace_mcp

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 and creation
• 📊 Google Sheets: Comprehensive spreadsheet management with flexible cell operations
• 🖼️ Google Slides: Presentation management with slide creation, updates, and content manipulation
• 📝 Google Forms: Form creation, retrieval, publish settings, and response management
• 💬 Google Chat: Space management and messaging capabilities
• 🔄 Multiple Transports: HTTP with SSE fallback, OpenAPI compatibility via mcpo
• ⚡ High Performance: Service caching, thread-safe sessions, FastMCP integration
• 🧩 Developer Friendly: Minimal boilerplate, automatic service injection, centralized configuration

Run instantly without manual installation - you must set the GOOGLE_CLIENT_SECRETS environment variable with the path to your client_secret.json when using uvx as you won't have a repo directory to pull from.

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

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

# 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://.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, Chat
   • Download credentials as client_secret.json in project root
     • To use a different location for client_secret.json, you can set the GOOGLE_CLIENT_SECRETS environment variable with that path
   • Add redirect URI: http://localhost:8000/oauth2callback

2. Environment:

   export OAUTHLIB_INSECURE_TRANSPORT=1  # Development only

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). This affects the server_url used for Gemini native function calling and the OAUTH_REDIRECT_URI.
   • WORKSPACE_MCP_PORT: Sets the port the server listens on (default: 8000). This affects the server_url, port, and OAUTH_REDIRECT_URI.

# 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
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, chat

The server supports two transport modes:

Option 1: Auto-install (Recommended)

python install_claude.py

Option 2: Manual Configuration

1. Open Claude Desktop Settings → Developer → Edit Config
2. This creates/opens the config file at:
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
3. Add the server configuration:

{
  "mcpServers": {
    "google_workspace": {
      "command": "uvx",
      "args": ["workspace-mcp"]
    }
  }
}

Alternative (Development Installation):

{
  "mcpServers": {
    "google_workspace": {
      "command": "uv",
      "args": ["run", "main.py"],
      "cwd": "/path/to/google_workspace_mcp"
    }
  }
}

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:

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.