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-mcpVerified import paths — ran on the pinned version, not inferred.
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.
Avoid DWD unless absolutely necessary. For typical use, prefer standard OAuth 2.0 'Desktop application' or 'Web application' credentials and manage scopes carefully.
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.
To avoid weekly token expiry, ensure your OAuth consent screen is published to 'In production' status.
Upgrade to v1.17.3 or later to ensure credential file security. Review existing credential file permissions if running older versions.
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.
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"`.
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.
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.
Go to the Google Cloud Console, navigate to 'APIs & Services' > 'Library', and enable the specific API mentioned in the error message.