Comprehensive, highly performant Google Workspace Streamable HTTP & SSE MCP Server for Calendar, Gmail, Docs, Sheets, Slides & Drive
This is the single most feature-complete Google Workspace MCP server now with 1-click Claude installation
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.
See it in action:
This README was written with AI assistance, and here's why that matters
As a solo dev building open source tools that many never see outside use, 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 7/10/25.
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.
mcpogoogle_workspace_mcp.dxt from the “Releases” pageWhy 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.
| Variable | Purpose |
|---|---|
GOOGLE_OAUTH_CLIENT_ID | OAuth client ID from Google Cloud |
GOOGLE_OAUTH_CLIENT_SECRET | OAuth client secret |
USER_GOOGLE_EMAIL (optional) | Default email for single-user auth |
GOOGLE_PSE_API_KEY (optional) | API key for Google Custom Search - see Custom Search Setup |
GOOGLE_PSE_ENGINE_ID (optional) | Programmable Search Engine ID for Custom Search |
OAUTHLIB_INSECURE_TRANSPORT=1 | Development only (allows http:// redirect) |
Claude Desktop stores these securely in the OS keychain; set them once in the extension pane.
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
Option B: File-based (Traditional)
client_secret.json in project rootGOOGLE_CLIENT_SECRET_PATH (or legacy GOOGLE_CLIENT_SECRETS) environment variable with the file pathCredential Loading Priority:
GOOGLE_OAUTH_CLIENT_ID, GOOGLE_OAUTH_CLIENT_SECRET)GOOGLE_CLIENT_SECRET_PATH or GOOGLE_CLIENT_SECRETS environment variableclient_secret.json in project root)Why Environment Variables?
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
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 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 casesTo use the Google Custom Search tools, you need to:
Create a Programmable Search Engine:
Get an API Key:
GOOGLE_PSE_API_KEY environment variable with your API keyConfigure Environment Variables:
GOOGLE_PSE_API_KEY to your Custom Search API keyGOOGLE_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 supports two transport modes:
Guided Setup (Recommended if not using DXT)
python install_claude.py
This script automatically:
After running the script, just restart Claude Desktop and you're ready to go.
Manual Claude Configuration (Alternative)
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.json{
"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 legacyGOOGLE_CLIENT_SECRETS) environment variable to point to yourclient_secret.jsonfile.
# 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:
http://localhost:8000/oauth2callback for consistencyWhen calling a tool:
Note: All tools support automatic authentication via
@require_google_service()decorators with 30-minute service caching.
calendar_tools.py)| Tool | Description |
|---|---|
list_calendars | List accessible calendars |
get_events | Retrieve events with time range filtering |
get_event | Fetch detailed information of a single event by ID |
create_event | Create events (all-day or timed) with optional Drive file attachments |
modify_event | Update existing events |
delete_event | Remove events |
drive_tools.py)| Tool | Description |
|---|---|
search_drive_files | Search files with query syntax |
get_drive_file_content | Read file content (supports Office formats) |
list_drive_items | List folder contents |
create_drive_file | Create new files or fetch content from public URLs |
gmail_tools.py)| Tool | Description |
|---|---|
search_gmail_messages | Search with Gmail operators |
get_gmail_message_content | Retrieve message content |
send_gmail_message | Send emails |
draft_gmail_message | Create drafts |
docs_tools.py)| Tool | Description |
|---|---|
search_docs | Find documents by name |
get_doc_content | Extract document text |
list_docs_in_folder | List docs in folder |
create_doc | Create new documents |
read_doc_comments | Read all comments and replies |
create_doc_comment | Create new comments |
reply_to_comment | Reply to existing comments |
resolve_comment | Resolve comments |
sheets_tools.py)| Tool | Description |
|---|---|
list_spreadsheets | List accessible spreadsheets |
get_spreadsheet_info | Get spreadsheet metadata |
read_sheet_values | Read cell ranges |
modify_sheet_values | Write/update/clear cells |
create_spreadsheet | Create new spreadsheets |
create_sheet | Add sheets to existing files |
read_sheet_comments | Read all comments and replies |
create_sheet_comment | Create new comments |
reply_to_sheet_comment | Reply to existing comments |
resolve_sheet_comment | Resolve comments |
slides_tools.py)| Tool | Description |
|---|---|
create_presentation | Create new presentations |
get_presentation | Retrieve presentation details |
batch_update_presentation | Apply multiple updates at once |
get_page | Get specific slide information |
get_page_thumbnail | Generate slide thumbnails |
read_presentation_comments | Read all comments and replies |
create_presentation_comment | Create new comments |
reply_to_presentation_comment | Reply to existing comments |
resolve_presentation_comment | Resolve comments |
forms_tools.py)| Tool | Description |
|---|---|
create_form | Create new forms with title and description |
get_form | Retrieve form details, questions, and URLs |
set_publish_settings | Configure form template and authentication settings |
get_form_response | Get individual form response details |
list_form_responses | List all responses to a form with pagination |
tasks_tools.py)| Tool | Description |
|---|---|
list_task_lists | List all task lists with pagination support |
get_task_list | Retrieve details of a specific task list |
create_task_list | Create new task lists with custom titles |
update_task_list | Modify existing task list titles |
delete_task_list | Remove task lists and all contained tasks |
list_tasks | List tasks in a specific list with filtering options |
get_task | Retrieve detailed information about a specific task |
create_task | Create new tasks with title, notes, due dates, and hierarchy |
update_task | Modify task properties including title, notes, status, and due dates |
delete_task | Remove tasks from task lists |
move_task | Reposition tasks within lists or move between lists |
clear_completed_tasks | Hide all completed tasks from a list |
chat_tools.py)| Tool | Description |
|---|---|
list_spaces | List chat spaces/rooms |
get_messages | Retrieve space messages |
send_message | Send messages to spaces |
search_messages | Search across chat history |
search_tools.py)| Tool | Description |
|---|---|
search_custom | Perform web searches using Programmable Search Engine |
get_search_engine_info | Retrieve search engine metadata and configuration |
search_custom_siterestrict | Search within specific sites/domains |
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
SCOPE_GROUPS for easy maintenance@require_multiple_services() for complex toolsclient_secret.json or .credentials/ directoryhttp://localhost:8000/oauth2callback for development (requires OAUTHLIB_INSECURE_TRANSPORT=1)mcpo over networksTo 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.
http://localhost:8001/google_workspace (matching the mcpo base URL and server name from config.json)--api-key with mcpo, enter it as the API KeyThe Google Workspace tools should now be available when interacting with models in Open WebUI.
MIT License - see LICENSE file for details.
FAQs
Comprehensive, highly performant Google Workspace Streamable HTTP & SSE MCP Server for Calendar, Gmail, Docs, Sheets, Slides & Drive
We found that workspace-mcp demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
A flawed sandbox in @nestjs/devtools-integration lets attackers run code on your machine via CSRF, leading to full Remote Code Execution (RCE).
Product
Customize license detection with Socket’s new license overlays: gain control, reduce noise, and handle edge cases with precision.
Product
Socket now supports Rust and Cargo, offering package search for all users and experimental SBOM generation for enterprise projects.