The Google Workspace MCP Server enables seamless integration with Google Workspace services, providing:
- Authentication: Secure OAuth 2.0 flow for Google Workspace access
- Gmail: Search, read, send, and manage emails, drafts, threads, and labels
- Google Drive: Search, access, and manage files/folders including shared drives and Office formats
- Google Calendar: Create, modify, delete, and retrieve events and calendars
- Google Docs: Search, read, create, and manage documents
- Google Sheets: Create, read, modify spreadsheets and cell values
- Google Forms: Create forms, manage publish settings, and retrieve responses
- Google Chat: Manage chat spaces, send messages, and search chat history
The server supports multiple transport methods (HTTP, SSE) and integrates with AI assistants like Claude Desktop and Open WebUI.
Enables complete email management including searching messages, retrieving content, sending emails, and creating drafts with full support for Gmail query syntax.
Provides full calendar management capabilities including listing calendars, fetching events, creating/modifying/deleting events with support for all-day and timed events.
Allows searching for documents, reading document content, listing documents in folders, and creating new documents directly from chat.
Enables searching files, listing folder contents, reading file content, and creating new files with support for extraction and retrieval of Microsoft Office formats.
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.
See it in action:
A quick plug for AI-Enhanced Docs
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
- Complete Gmail management, end to end coverage
- Full calendar management with advanced features
- File operations with Office format support
- Document creation, editing & comments
- Deep, exhaustive support for fine grained editing
≡ Forms • @ Chat • ≡ Sheets • ≡ Slides
- Form creation, publish settings & response management
- Space management & messaging capabilities
- Spreadsheet operations with flexible cell management
- Presentation creation, updates & content manipulation
⊠ Authentication & Security
- Advanced OAuth 2.0 & OAuth 2.1 support
- Automatic token refresh & session management
- Transport-aware callback handling
- Multi-user bearer token authentication
- Innovative CORS proxy architecture
✓ Tasks • ◆ Custom Search • ↻ Transport Support
- Full support for all MCP Transports
- OpenAPI compatibility via
mcpo
- Task & task list management with hierarchy
- Programmable Search Engine (PSE) integration
▶ Quick Start
⊠ Credentials
▶ Launch Commands
★ Tool Tiers
- ●
core
- Essential tools - ◐
extended
- Core + extras - ○
complete
- Everything Details →
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
Required
Variable | Purpose |
---|---|
GOOGLE_OAUTH_CLIENT_ID | OAuth client ID from Google Cloud |
GOOGLE_OAUTH_CLIENT_SECRET | OAuth client secret |
OAUTHLIB_INSECURE_TRANSPORT=1 | Development only (allows http:// redirect) |
Optional
Variable | Purpose |
---|---|
USER_GOOGLE_EMAIL | Default email for single-user auth |
GOOGLE_PSE_API_KEY | API key for Custom Search |
GOOGLE_PSE_ENGINE_ID | Search Engine ID for Custom Search |
MCP_ENABLE_OAUTH21 | Set to true for OAuth 2.1 support |
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
1. Create Project
2. OAuth Credentials
Download & save credentials
3. Enable APIs
See quick links below
Complete Setup Process:
- Create OAuth 2.0 Credentials - Visit Google Cloud Console
- Create a new project (or use existing)
- Navigate to APIs & Services → Credentials
- Click Create Credentials → OAuth Client ID
- Choose Desktop Application as the application type (no redirect URIs needed!)
- Download credentials and note the Client ID and Client Secret
- Enable Required APIs - In APIs & Services → Library
- Search for and enable each required API
- Or use the quick links below for one-click enabling
- Configure Environment - Set your credentials:
- Enable Google Calendar API
- Enable Google Drive API
- Enable Gmail API
- Enable Google Docs API
- Enable Google Sheets API
- Enable Google Slides API
- Enable Google Forms API
- Enable Google Tasks API
- Enable Google Chat API
- Enable Google Custom Search API
1.1. Credentials: See Credential Configuration for detailed setup options
- Environment Configuration:
◆ Development Mode
Allows HTTP redirect URIs
@ Default User
Single-user authentication
◆ Custom Search
Optional: Search API setup
- Server Configuration:
◆ 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
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
1. Create Search Engine
2. Get API Key
3. Set Variables
Configure in environment
Complete Setup Process:
- Create Search Engine - Visit the Control Panel
- Choose "Search the entire web" or specify sites
- Copy the Search Engine ID (looks like:
017643444788157684527:6ivsjbpxpqw
)
- Enable API & Get Key - Visit Google Developers Console
- Enable "Custom Search API" in your project
- Create credentials → API Key
- Restrict key to Custom Search API (recommended)
- Configure Environment - Add to your shell or
.env
:
Start the Server
▶ Quick Start
Default stdio mode
◆ HTTP Mode
Web interfaces & debugging
@ Single User
Simplified authentication
▶ Selective Tool Loading
★ Tool Tiers
◆ Docker Deployment
Available Services: gmail
• drive
• calendar
• docs
• sheets
• forms
• tasks
• chat
• search
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 (--tool-tier core
)
Essential tools for everyday tasks. Perfect for light usage with minimal API quotas. Includes search, read, create, and basic modify operations across all services.
● Extended (--tool-tier extended
)
Core functionality plus management tools. Adds labels, folders, batch operations, and advanced search. Ideal for regular usage with moderate API needs.
● Complete (--tool-tier complete
)
Full API access including comments, headers/footers, publishing settings, and administrative functions. For power users needing maximum functionality.
Important Notes
▶ Start with core
and upgrade as needed
▶ Tiers are cumulative – each includes all previous
▶ Mix and match with --tools
for specific services
▶ Configuration in core/tool_tiers.yaml
▶ Authentication included in all tiers
Usage Examples
📋 Credential Configuration
🚀 Environment Variables
Best for production
📁 File-based
Traditional method
⚡ .env File
Best for development
Loading Priority
- Environment variables (
export VAR=value
) .env
file in project rootclient_secret.json
viaGOOGLE_CLIENT_SECRET_PATH
- Default
client_secret.json
in project root
Why Environment Variables?
- ✅ Docker/K8s ready - Native container support
- ✅ Cloud platforms - Heroku, Railway, Vercel
- ✅ CI/CD pipelines - GitHub Actions, Jenkins
- ✅ No secrets in git - Keep credentials secure
- ✅ Easy rotation - Update without code changes
🧰 Available Tools
Note: All tools support automatic authentication via
@require_google_service()
decorators with 30-minute service caching.
📅 Google Calendar calendar_tools.py
Tool | Tier | Description |
---|---|---|
list_calendars | Core | List accessible calendars |
get_events | Core | Retrieve events with time range filtering |
create_event | Core | Create events with attachments & reminders |
modify_event | Core | Update existing events |
delete_event | Extended | Remove events |
📁 Google Drive drive_tools.py
Tool | Tier | Description |
---|---|---|
search_drive_files | Core | Search files with query syntax |
get_drive_file_content | Core | Read file content (Office formats) |
list_drive_items | Extended | List folder contents |
create_drive_file | Core | Create files or fetch from URLs |
📧 Gmail gmail_tools.py
Tool | Tier | Description |
---|---|---|
search_gmail_messages | Core | Search with Gmail operators |
get_gmail_message_content | Core | Retrieve message content |
get_gmail_messages_content_batch | Core | Batch retrieve message content |
send_gmail_message | Core | Send emails |
get_gmail_thread_content | Extended | Get full thread content |
modify_gmail_message_labels | Extended | Modify message labels |
list_gmail_labels | Extended | List available labels |
manage_gmail_label | Extended | Create/update/delete labels |
draft_gmail_message | Extended | Create drafts |
get_gmail_threads_content_batch | Complete | Batch retrieve thread content |
batch_modify_gmail_message_labels | Complete | Batch modify labels |
start_google_auth | Complete | Initialize authentication |
📝 Google Docs docs_tools.py
Tool | Tier | Description |
---|---|---|
get_doc_content | Core | Extract document text |
create_doc | Core | Create new documents |
modify_doc_text | Core | Modify document text |
search_docs | Extended | Find documents by name |
find_and_replace_doc | Extended | Find and replace text |
list_docs_in_folder | Extended | List docs in folder |
insert_doc_elements | Extended | Add tables, lists, page breaks |
insert_doc_image | Complete | Insert images from Drive/URLs |
update_doc_headers_footers | Complete | Modify headers and footers |
batch_update_doc | Complete | Execute multiple operations |
inspect_doc_structure | Complete | Analyze document structure |
create_table_with_data | Complete | Create data tables |
debug_table_structure | Complete | Debug table issues |
*_document_comments | Complete | Read, Reply, Create, Resolve |
📊 Google Sheets sheets_tools.py
Tool | Tier | Description |
---|---|---|
read_sheet_values | Core | Read cell ranges |
modify_sheet_values | Core | Write/update/clear cells |
create_spreadsheet | Core | Create new spreadsheets |
list_spreadsheets | Extended | List accessible spreadsheets |
get_spreadsheet_info | Extended | Get spreadsheet metadata |
create_sheet | Complete | Add sheets to existing files |
*_sheet_comment | Complete | Read/create/reply/resolve comments |
🖼️ Google Slides slides_tools.py
Tool | Tier | Description |
---|---|---|
create_presentation | Core | Create new presentations |
get_presentation | Core | Retrieve presentation details |
batch_update_presentation | Extended | Apply multiple updates |
get_page | Extended | Get specific slide information |
get_page_thumbnail | Extended | Generate slide thumbnails |
*_presentation_comment | Complete | Read/create/reply/resolve comments |
📝 Google Forms forms_tools.py
Tool | Tier | Description |
---|---|---|
create_form | Core | Create new forms |
get_form | Core | Retrieve form details & URLs |
set_publish_settings | Complete | Configure form settings |
get_form_response | Complete | Get individual responses |
list_form_responses | Extended | List all responses with pagination |
✓ Google Tasks tasks_tools.py
Tool | Tier | Description |
---|---|---|
list_tasks | Core | List tasks with filtering |
get_task | Core | Retrieve task details |
create_task | Core | Create tasks with hierarchy |
update_task | Core | Modify task properties |
delete_task | Extended | Remove tasks |
move_task | Complete | Reposition tasks |
clear_completed_tasks | Complete | Hide completed tasks |
*_task_list | Complete | List/get/create/update/delete task lists |
💬 Google Chat chat_tools.py
Tool | Tier | Description |
---|---|---|
list_spaces | Extended | List chat spaces/rooms |
get_messages | Core | Retrieve space messages |
send_message | Core | Send messages to spaces |
search_messages | Core | Search across chat history |
🔍 Google Custom Search search_tools.py
Tool | Tier | Description |
---|---|---|
search_custom | Core | Perform web searches |
get_search_engine_info | Complete | Retrieve search engine metadata |
search_custom_siterestrict | Extended | Search within specific domains |
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)
- 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:
2. Advanced / Cross-Platform Installation
If you’re developing, deploying to servers, or using another MCP-capable client, keep reading.
Instant CLI (uvx)
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
.
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.
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
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:
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
Requires Python 3.10+ and uvx. The package is available on PyPI.
Development Installation
For development or customization:
Development Installation (For Contributors):
HTTP Mode (For debugging or web interfaces)
If you need to use HTTP mode with Claude Desktop:
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
Adding New Tools
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
Credential Store System
The server includes an abstract credential store API and a default backend for managing Google OAuth credentials with support for multiple storage backends:
Features:
- Abstract Interface:
CredentialStore
base class defines standard operations (get, store, delete, list users) - Local File Storage:
LocalDirectoryCredentialStore
implementation stores credentials as JSON files - Configurable Storage: Environment variable
GOOGLE_MCP_CREDENTIALS_DIR
sets storage location - Multi-User Support: Store and manage credentials for multiple Google accounts
- Automatic Directory Creation: Storage directory is created automatically if it doesn't exist
Configuration:
Usage Example:
The credential store automatically handles credential serialization, expiry parsing, and provides error handling for storage operations.
⊠ 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
▶ Instant Start (No Config)
◆ Manual Configuration
- Create
config.json
:
- Start MCPO:
≡ 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.
Validations:
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Tools
Google Workspace MCP Server
Related MCP Servers
- -securityAlicense-qualityMCP server to interact with Google produts.Last updated -415PythonMIT License
- Python
- MIT License
- AsecurityAlicenseAqualityWayback Machine MCP ServerLast updated -212TypeScriptMIT License