taylorwilsdon/google_workspace_mcp
If you are the rightful owner of google_workspace_mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
The Google Workspace MCP Server is a comprehensive solution for integrating Google Workspace services with AI assistants, providing natural language control over various Google applications.
Google Workspace MCP Server
Full natural language control over Google Calendar, Drive, Gmail, Docs, Sheets, Slides, Forms, Tasks, and Chat through all MCP clients, AI assistants and developer tools.
The most feature-complete Google Workspace MCP server, now with Remote OAuth2.1 multi-user support and 1-click Claude installation.
Support for all free Google accounts (Gmail, Docs, Drive etc) & Google Workspace plans (Starter, Standard, Plus, Enterprise, Non Profit) with expanded app options like Chat & Spaces.
Interested in a private cloud instance? That can be arranged.
See it in action:
A quick plug for AI-Enhanced Docs
β But why?
This README was written with AI assistance, and here's why that matters
As a solo dev building open source tools, comprehensive documentation often wouldn't happen without AI help. Using agentic dev tools like Roo & Claude Code that understand the entire codebase, AI doesn't just regurgitate generic content - it extracts real implementation details and creates accurate, specific documentation.
In this case, Sonnet 4 took a pass & a human (me) verified them 8/16/25.
Overview
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.
Simplified Setup: Now uses Google Desktop OAuth clients - no redirect URIs or port configuration needed!
Features
@ Gmail β’ β‘ Drive β’ β§ Calendar β‘ Docs
β‘ Forms β’ @ Chat β’ β‘ Sheets β’ β‘ Slides
|
β Authentication & Security
β Tasks β’ β Custom Search β’ β» Transport Support
|
βΆ Quick Start
β‘ Quick Reference Card β Essential commands & configs at a glance
β Credentials
|
βΆ Launch Commands
|
β Tool Tiers
|
1. One-Click Claude Desktop Install (Recommended)
- Download: Grab the latest
google_workspace_mcp.dxt
from the βReleasesβ page - Install: Double-click the file β Claude Desktop opens and prompts you to Install
- Configure: In Claude Desktop β Settings β Extensions β Google Workspace MCP, paste your Google OAuth credentials
- 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.
Required Configuration
β Environment Variables β Click to configure in Claude Desktop
Required
|
Optional
|
Claude Desktop stores these securely in the OS keychain; set them once in the extension pane.
Prerequisites
- Python 3.10+
- uvx (for instant installation) or uv (for development)
- Google Cloud Project with OAuth 2.0 credentials
Configuration
β Google Cloud Setup β OAuth 2.0 credentials & API enablement
1. Create Project
|
2. OAuth Credentials
Download & save credentials |
3. Enable APIs
See quick links below |
β‘ OAuth Credential Setup Guide β Step-by-step instructionsComplete Setup Process:
|
β₯ Quick API Enable Links β One-click enable each Google API
You can enable each one by clicking the links below (make sure you're logged into the Google Cloud Console and have the correct project selected):1.1. Credentials: See Credential Configuration for detailed setup options
- Environment Configuration:
β Environment Variables β Configure your runtime environment
β Development Mode
Allows HTTP redirect URIs |
@ Default User
Single-user authentication |
β Custom Search
Optional: Search API setup |
- Server Configuration:
β Server Settings β Customize ports, URIs & proxies
β Base Configuration
Server URL & port settings |
β» Proxy Support
Leverage multi-user OAuth2.1 clients |
@ Default Email
Skip email in auth flows in single user mode |
β‘ Configuration Details β Learn more about each setting
Variable | Description | Default |
---|---|---|
WORKSPACE_MCP_BASE_URI | Base server URI (no port) | http://localhost |
WORKSPACE_MCP_PORT | Server listening port | 8000 |
GOOGLE_OAUTH_REDIRECT_URI | Override OAuth callback URL | Auto-constructed |
USER_GOOGLE_EMAIL | Default auth email | None |
Google Custom Search Setup
β Custom Search Configuration β Enable web search capabilities
1. Create Search Engine
|
2. Get API Key
|
3. Set Variables
Configure in environment |
β‘ Quick Setup Guide β Step-by-step instructionsComplete Setup Process:
|
Start the Server
βΆ Launch Commands β Choose your startup mode
βΆ Quick Start
Default stdio mode |
β HTTP Mode
Web interfaces & debugging |
@ Single User
Simplified authentication |
β Advanced Options β Tool selection, tiers & DockerβΆ Selective Tool Loading
β Tool Tiers
β Docker Deployment
Available Services: |
Tool Tiers
The server organizes tools into three progressive tiers for simplified deployment. Choose a tier that matches your usage needs and API quota requirements.
Available Tiersβ Core ( β Extended ( β Complete ( |
Important NotesβΆ Start with |
Usage Examples
# Basic tier selection
uv run main.py --tool-tier core # Start with essential tools only
uv run main.py --tool-tier extended # Expand to include management features
uv run main.py --tool-tier complete # Enable all available functionality
# Selective service loading with tiers
uv run main.py --tools gmail drive --tool-tier core # Core tools for specific services
uv run main.py --tools gmail --tool-tier extended # Extended Gmail functionality only
uv run main.py --tools docs sheets --tool-tier complete # Full access to Docs and Sheets
π Credential Configuration
π OAuth Credentials Setup β Essential for all installations
π Environment Variables
Best for production |
π File-based
Traditional method |
β‘ .env File
Best for development |
π Credential Loading Details β Understanding priority & best practicesLoading Priority
Why Environment Variables?
|
π§° Available Tools
Note: All tools support automatic authentication via
@require_google_service()
decorators with 30-minute service caching.
π Google Calendar
|
π Google Drive
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
π§ Gmail
|
π Google Docs
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
π Google Sheets
|
πΌοΈ Google Slides
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
π Google Forms
|
β Google Tasks
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
π¬ Google Chat
|
π Google Custom Search
|
Tool Tier Legend:
- β’ Core: Essential tools for basic functionality β’ Minimal API usage β’ Getting started
- β’ Extended: Core tools + additional features β’ Regular usage β’ Expanded capabilities
- β’ Complete: All available tools including advanced features β’ Power users β’ Full API access
Connect to Claude Desktop
The server supports two transport modes:
Stdio Mode (Default - Recommended for Claude Desktop)
In general, you should use the one-click DXT installer package for Claude Desktop.
If you are unable to for some reason, you can configure it manually via claude_desktop_config.json
Manual Claude Configuration (Alternative)
π Claude Desktop JSON Config β Click for manual setup instructions
-
Open Claude Desktop Settings β Developer β Edit Config
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
- Windows:
%APPDATA%\Claude\claude_desktop_config.json
- macOS:
-
Add the server configuration:
{
"mcpServers": {
"google_workspace": {
"command": "uvx",
"args": ["workspace-mcp"],
"env": {
"GOOGLE_OAUTH_CLIENT_ID": "your-client-id",
"GOOGLE_OAUTH_CLIENT_SECRET": "your-secret",
"OAUTHLIB_INSECURE_TRANSPORT": "1"
}
}
}
}
2. Advanced / Cross-Platform Installation
If youβre developing, deploying to servers, or using another MCP-capable client, keep reading.
Instant CLI (uvx)
β‘ Quick Start with uvx β No installation required!
# Requires Python 3.10+ and uvx
# First, set credentials (see Credential Configuration above)
uvx workspace-mcp --tool-tier core # or --tools gmail drive calendar
Note: Configure OAuth credentials before running. Supports environment variables,
.env
file, orclient_secret.json
.
OAuth 2.1 Support (Multi-User Bearer Token Authentication)
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.
π Innovative CORS Proxy Architecture β Advanced OAuth 2.1 details
This implementation solves two critical challenges when using Google OAuth in browser environments:
-
Dynamic Client Registration: Google doesn't support OAuth 2.1 dynamic client registration. Our server provides a clever proxy that accepts any client registration request and returns the pre-configured Google OAuth credentials, allowing standards-compliant clients to work seamlessly.
-
CORS Issues: Google's OAuth endpoints don't include CORS headers, blocking browser-based clients. We implement intelligent proxy endpoints that:
- Proxy authorization server discovery requests through
/auth/discovery/authorization-server/{server}
- Proxy token exchange requests through
/oauth2/token
- Add proper CORS headers to all responses
- Maintain security by only proxying to known Google OAuth endpoints
This architecture enables any OAuth 2.1 compliant client to authenticate users through Google, even from browser environments, without requiring changes to the client implementation.
MCP Inspector: No additional configuration needed with desktop OAuth client.
Claude Code Inspector: No additional configuration needed with desktop OAuth client.
VS Code MCP Client Support
π VS Code Configuration β Setup for VS Code MCP extension
{
"servers": {
"google-workspace": {
"url": "http://localhost:8000/mcp/",
"type": "http"
}
}
}
Reverse Proxy Setup
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
).
You also have options for:
| OAUTH_CUSTOM_REDIRECT_URIS
(optional) | Comma-separated list of additional redirect URIs |
| OAUTH_ALLOWED_ORIGINS
(optional) | Comma-separated list of additional CORS origins |
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
andWORKSPACE_MCP_PORT
- Your reverse proxy must forward
/oauth2callback
requests to the MCP server
π Advanced uvx Commands β More startup options
# Configure credentials first (see Credential Configuration section)
# Start with specific tools only
uvx workspace-mcp --tools gmail drive calendar tasks
# Start with tool tiers (recommended for most users)
uvx workspace-mcp --tool-tier core # Essential tools
uvx workspace-mcp --tool-tier extended # Core + additional features
uvx workspace-mcp --tool-tier complete # All tools
# Start in HTTP mode for debugging
uvx workspace-mcp --transport streamable-http
Requires Python 3.10+ and uvx. The package is available on PyPI.
Development Installation
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):
π§ Developer Setup JSON β For contributors & customization
{
"mcpServers": {
"google_workspace": {
"command": "uv",
"args": [
"run",
"--directory",
"/path/to/repo/google_workspace_mcp",
"main.py"
],
"env": {
"GOOGLE_OAUTH_CLIENT_ID": "your-client-id",
"GOOGLE_OAUTH_CLIENT_SECRET": "your-secret",
"OAUTHLIB_INSECURE_TRANSPORT": "1"
}
}
}
}
HTTP Mode (For debugging or web interfaces)
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.
First-Time Authentication
The server uses Google Desktop OAuth for simplified authentication:
- No redirect URIs needed: Desktop OAuth clients handle authentication without complex callback URLs
- Automatic flow: The server manages the entire OAuth process transparently
- Transport-agnostic: Works seamlessly in both stdio and HTTP modes
When calling a tool:
- Server returns authorization URL
- Open URL in browser and authorize
- Google provides an authorization code
- Paste the code when prompted (or it's handled automatically)
- Server completes authentication and retries your request
β Development
Project Structure
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
Adding New Tools
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
Architecture Highlights
- 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
β Security
- Credentials: Never commit
.env
,client_secret.json
or the.credentials/
directory to source control! - OAuth Callback: Uses
http://localhost:8000/oauth2callback
for development (requiresOAUTHLIB_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 & OAuth 2.1 and configure accordingly
- Network Exposure: Consider authentication when using
mcpo
over networks - Scope Minimization: Tools request only necessary permissions
β Integration with Open WebUI
β Open WebUI Integration β Connect to Open WebUI as tool provider
βΆ Instant Start (No Config)
|
β Manual Configuration
|
β‘ Configure Open WebUI
- Navigate to Settings β Connections β Tools
- Click Add Tool and enter:
- Server URL:
http://localhost:8001/google_workspace
- API Key: Your mcpo
--api-key
(if set)
- Server URL:
- Save - Google Workspace tools are now available!
β‘ License
MIT License - see LICENSE
file for details.