{"id":9411,"library":"workspace-mcp","title":"Google Workspace MCP Server","description":"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.","status":"active","version":"1.19.0","language":"en","source_language":"en","source_url":"https://github.com/taylorwilsdon/google_workspace_mcp","tags":["google-workspace","mcp","ai","server","oauth","gmail","calendar","drive","docs","sheets","slides","fastmcp"],"install":[{"cmd":"pip install workspace-mcp","lang":"bash","label":"Standard pip installation"},{"cmd":"uvx workspace-mcp","lang":"bash","label":"Instant run CLI (requires 'uv' installed)"}],"dependencies":[{"reason":"Core underlying framework for building MCP servers and tools, essential for `workspace-mcp` functionality and performance.","package":"fastmcp","optional":false}],"imports":[{"note":"Used when defining a custom MCP server or extending `workspace-mcp` with new tools.","symbol":"FastMCP","correct":"from fastmcp import FastMCP"},{"note":"Decorator used to define tools that require specific Google Workspace service access and OAuth scopes.","symbol":"require_google_service","correct":"from auth.service_decorator import require_google_service"}],"quickstart":{"code":"import os\nimport subprocess\n\n# --- Step 1: Set up Google OAuth Credentials ---\n# Create a Google Cloud Project, enable necessary APIs (e.g., Gmail API, Google Calendar API, Google Drive API).\n# Configure the OAuth consent screen (External, add yourself as test user, add scopes).\n# Create OAuth 2.0 credentials: Choose 'Desktop application' type.\n# Note your Client ID and Client Secret. Set them as environment variables.\n# For a web application, ensure redirect URIs and origins match your deployment.\n\n# Replace with your actual Google OAuth Client ID and Secret\nos.environ['GOOGLE_OAUTH_CLIENT_ID'] = os.environ.get('GOOGLE_OAUTH_CLIENT_ID', 'YOUR_GOOGLE_CLIENT_ID')\nos.environ['GOOGLE_OAUTH_CLIENT_SECRET'] = os.environ.get('GOOGLE_OAUTH_CLIENT_SECRET', 'YOUR_GOOGLE_CLIENT_SECRET')\n\n# Optional: For local legacy HTTP callback flows, may be required for certain setups.\n# os.environ['OAUTHLIB_INSECURE_TRANSPORT'] = '1'\n\n# --- Step 2: Start the Google Workspace MCP Server ---\n# 'uvx' is recommended for instant run. Ensure 'uv' is installed (`pip install uv`).\n# '--transport streamable-http' is recommended for modern MCP clients.\n# '--tool-tier core' or explicit '--tools gmail drive calendar' selects services.\n\nprint(\"Starting Google Workspace MCP Server...\")\ntry:\n    subprocess.run(\n        [\"uvx\", \"workspace-mcp\", \"--transport\", \"streamable-http\", \"--tool-tier\", \"core\"],\n        check=True\n    )\nexcept FileNotFoundError:\n    print(\"Error: 'uvx' command not found. Please install 'uv' with `pip install uv`.\")\nexcept subprocess.CalledProcessError as e:\n    print(f\"Server exited with an error: {e}\")\n\nprint(\"Server stopped.\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Avoid DWD unless absolutely necessary. For typical use, prefer standard OAuth 2.0 'Desktop application' or 'Web application' credentials and manage scopes carefully.","message":"Using '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.","severity":"gotcha","affected_versions":">=1.18.0"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"To avoid weekly token expiry, ensure your OAuth consent screen is published to 'In production' status.","message":"OAuth tokens for applications in 'Testing' status on Google Cloud expire after 7 days, requiring frequent re-authentication. This can be disruptive during development.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade to v1.17.3 or later to ensure credential file security. Review existing credential file permissions if running older versions.","message":"Version 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.","severity":"breaking","affected_versions":"<1.17.3"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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\"`.","cause":"The server cannot find the necessary Google OAuth Client ID to initiate authentication.","error":"GOOGLE_CLIENT_ID environment variable is required"},{"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.","cause":"The provided Google OAuth Client ID or Secret is incorrect, or the Google Cloud Project setup is incomplete.","error":"Invalid OAuth credentials"},{"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.","cause":"The cached OAuth token is invalid or expired, often due to app being in 'Testing' mode or a scope change.","error":"Token refresh failed"},{"fix":"Go to the Google Cloud Console, navigate to 'APIs & Services' > 'Library', and enable the specific API mentioned in the error message.","cause":"A Google Workspace API required by a tool (e.g., Gmail API, Drive API) has not been enabled in your Google Cloud Project.","error":"API not enabled"}]}