{"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":"python","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,"search_vec":"'1.19.0':71 '2.1':53 'activ':75 'ai':31,88 'assist':32 'authent':50 'backend':57 'cadenc':77 'calendar':23,92 'client':38 'comprehens':10 'control':61 'current':68 'design':16 'doc':25,94 'drive':28,93 'enhanc':83 'etc':29 'fastmcp':97 'featur':82 'frequent':79 'gmail':24,91 'googl':1,20,63,85 'google-workspac':84 'high':12 'integr':18 'languag':60 'librari':66 'maintain':73 'major':19 'mcp':3,7,35,87 'multi':37,48 'multi-cli':36 'multi-us':47 'natur':59 'oauth':52,90 'perform':13 'power':56 'protocol':39 'provid':54 'python':14 'releas':76 'server':4,15,89 'servic':22 'sheet':26,95 'singl':44 'single-us':43 'slide':27,96 'support':41 'updat':80 'user':45,49 'version':70 'via':33 'workspac':2,6,21,64,86 'workspace-mcp':5","created_at":"2026-04-16T18:50:04.528334+00:00","updated_at":"2026-04-16T18:50:04.528334+00:00","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"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.21.2","cli_name":"","cli_version":null,"type":"library","homepage":"https://workspacemcp.com","github":"https://github.com/taylorwilsdon/google_workspace_mcp","docs":"https://github.com/taylorwilsdon/google_workspace_mcp#readme","changelog":"https://github.com/taylorwilsdon/google_workspace_mcp/releases","pypi":"https://pypi.org/project/workspace-mcp/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["gcp","communication","crm-productivity","auth-security"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":null}}