Registry / gcp / workspace-mcp

workspace-mcp

JSON →
library1.21.2pypypi✓ verified 84d ago

Workspace-mcp is a comprehensive and highly performant Python server designed to integrate major Google Workspace services (Calendar, Gmail, Docs, Sheets, Slides, Drive, etc.) with AI assistants via the MCP (Multi-Client Protocol). It supports both single-user and multi-user authentication through OAuth 2.1, providing a powerful backend for natural language control over Google Workspace. The library is currently at version 1.19.0 and maintains an active release cadence with frequent updates and feature enhancements.

pip install workspace-mcp
INSTALL
IMPORT
SIG · WORKSPACE-MCP
W
workspace-mcp
gcppythonv1.21.2
Install
15.7s avg
Import
4199ms
Disk
238MB
Pass rate
8/ 10
Env Coverage8 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.21.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
✓ —
✓ 17.8s
py 3.11
✓ —
✓ 17.45s
py 3.12
✓ —
✓ 14.1s
py 3.13
✓ —
✓ 13.55s
py 3.9
✕ build_error
✕ build_error
238MB installed
● package 238MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

FastMCP
from fastmcp import FastMCP
Used when defining a custom MCP server or extending `workspace-mcp` with new tools.
require_google_service
from auth.service_decorator import require_google_service
Decorator used to define tools that require specific Google Workspace service access and OAuth scopes.

This quickstart demonstrates how to set up environment variables for Google OAuth and then start the `workspace-mcp` server using the `uvx` CLI tool. It requires a Google Cloud Project with OAuth 2.0 credentials configured for a 'Desktop application' and the necessary Workspace APIs enabled. The server will run and expose Google Workspace tools to compatible MCP clients.

import os import subprocess # --- Step 1: Set up Google OAuth Credentials --- # Create a Google Cloud Project, enable necessary APIs (e.g., Gmail API, Google Calendar API, Google Drive API). # Configure the OAuth consent screen (External, add yourself as test user, add scopes). # Create OAuth 2.0 credentials: Choose 'Desktop application' type. # Note your Client ID and Client Secret. Set them as environment variables. # For a web application, ensure redirect URIs and origins match your deployment. # Replace with your actual Google OAuth Client ID and Secret os.environ['GOOGLE_OAUTH_CLIENT_ID'] = os.environ.get('GOOGLE_OAUTH_CLIENT_ID', 'YOUR_GOOGLE_CLIENT_ID') os.environ['GOOGLE_OAUTH_CLIENT_SECRET'] = os.environ.get('GOOGLE_OAUTH_CLIENT_SECRET', 'YOUR_GOOGLE_CLIENT_SECRET') # Optional: For local legacy HTTP callback flows, may be required for certain setups. # os.environ['OAUTHLIB_INSECURE_TRANSPORT'] = '1' # --- Step 2: Start the Google Workspace MCP Server --- # 'uvx' is recommended for instant run. Ensure 'uv' is installed (`pip install uv`). # '--transport streamable-http' is recommended for modern MCP clients. # '--tool-tier core' or explicit '--tools gmail drive calendar' selects services. print("Starting Google Workspace MCP Server...") try: subprocess.run( ["uvx", "workspace-mcp", "--transport", "streamable-http", "--tool-tier", "core"], check=True ) except FileNotFoundError: print("Error: 'uvx' command not found. Please install 'uv' with `pip install uv`.") except subprocess.CalledProcessError as e: print(f"Server exited with an error: {e}") print("Server stopped.")
Debug
Known issues
gotchaUsing 'Domain-Wide Delegation (DWD) enabled service accounts' ('Scary Mode' from v1.18.0) has significant security implications. Only use if you fully understand the risks and have robust controls in place.
fix
Avoid DWD unless absolutely necessary. For typical use, prefer standard OAuth 2.0 'Desktop application' or 'Web application' credentials and manage scopes carefully.
affects: >=1.18.0
gotchaThe type of Google OAuth client ID (Desktop vs. Web application) must match your deployment. 'Desktop application' is for local CLI/stdio, while 'Web application' is for hosted HTTP deployments, reverse proxies, and browser-based clients. Using the wrong type can lead to authentication failures.
fix
Ensure your Google Cloud OAuth 2.0 Client ID is created as a 'Desktop application' for local use, or 'Web application' with correctly configured Authorized JavaScript origins and Redirect URIs for hosted environments.
affects: All versions
gotchaOAuth tokens for applications in 'Testing' status on Google Cloud expire after 7 days, requiring frequent re-authentication. This can be disruptive during development.
fix
To avoid weekly token expiry, ensure your OAuth consent screen is published to 'In production' status.
affects: All versions
breakingVersion 1.17.3 introduced a fix for credential file permissions (0600) and path traversal sanitization. Older versions might have been vulnerable to insecure file permissions or path traversal attacks related to credential files.
fix
Upgrade to v1.17.3 or later to ensure credential file security. Review existing credential file permissions if running older versions.
affects: <1.17.3
gotchaWhen setting up Google Custom Search (PSE), you must create a Search Engine ID in the Custom Search Control Panel and enable the 'Custom Search API' in your Google Cloud Project, also requiring an API key. This is a separate credential setup from general Workspace APIs.
fix
Follow the specific instructions for Custom Search Engine setup in the documentation, including obtaining a Search Engine ID and a restricted API key for the Custom Search API.
affects: All versions
Errors
Common errors & fixes
GOOGLE_CLIENT_ID environment variable is required
The server cannot find the necessary Google OAuth Client ID to initiate authentication.
fix
Set the `GOOGLE_OAUTH_CLIENT_ID` environment variable in your shell or configuration file. For example: `export GOOGLE_OAUTH_CLIENT_ID="your-client-id.apps.googleusercontent.com"`.
Invalid OAuth credentials
The provided Google OAuth Client ID or Secret is incorrect, or the Google Cloud Project setup is incomplete.
fix
Verify that your `GOOGLE_OAUTH_CLIENT_ID` and `GOOGLE_OAUTH_CLIENT_SECRET` environment variables are correct. Ensure all required Google Workspace APIs are enabled in your Google Cloud Project, and that your OAuth consent screen includes you as a test user if the app is in 'Testing' status.
Token refresh failed
The cached OAuth token is invalid or expired, often due to app being in 'Testing' mode or a scope change.
fix
Remove the stored token files (e.g., `~/.mcp/google-workspace-mcp/` or `~/.config/google-workspace-mcp/tokens.json`) to force re-authentication. If tokens expire frequently, ensure your OAuth app is published to 'In production' status.
API not enabled
A Google Workspace API required by a tool (e.g., Gmail API, Drive API) has not been enabled in your Google Cloud Project.
fix
Go to the Google Cloud Console, navigate to 'APIs & Services' > 'Library', and enable the specific API mentioned in the error message.
Upgrade
Version history
1.21.2latest on PyPI · released Jun 10, 2026
Audit
Dependencies
fastmcprequiredCore underlying framework for building MCP servers and tools, essential for `workspace-mcp` functionality and performance.
Agent activity
62 hits · last 30 days
node
56
Perplexity
1
OpenAI (training)
1
Resources
workspace-mcp — pip install workspace-mcp · libregistry