Google Workspace MCP Server
About
Control Gmail, Google Calendar, Docs, Sheets, Slides, Chat, Forms, Tasks, Search & Drive with AI - Comprehensive Google Workspace / G Suite MCP Server & CLI Tool
Details
- Author
- taylorwilsdon
- GitHub stars
- 2,798
- Downloads
- 1,016
- Categories
- Productivity, Other, AI
Jump to
- 12 service groups in one server: Gmail, Drive, Calendar, Docs, Sheets, Slides, Forms, Chat, Apps Script, Tasks, Contacts, and Custom Search
- Deep Workspace operations: search, read, create, edit, format, comment, share, organize, send, publish, and automate
- Full CLI support: list and invoke tools directly from terminals, scripts, Claude Code, Codex, and other coding-agent workflows
- Modern authentication: OAuth 2.0, OAuth 2.1 with PKCE, automatic token refresh, multi-user bearer authentication, external OAuth providers, and service-account domain-wide delegation
- Flexible tool control: cumulative core, extended, and complete tiers, per-service selection, read-only mode, and granular permission levels
- Deployment-ready: streamable HTTP, stateless containers, reverse proxies, encrypted OAuth storage backends, and centrally hosted multi-user instances
- Private by default: uses your OAuth client and Google Cloud project; the default data path is directly from your infrastructure to Google APIs
- Open source: MIT licensed, with no license server, SaaS dependency, usage reporting, or analytics
See the complete Workspace MCP documentation for tool parameters, permission controls, authentication modes, environment variables, and deployment guidance.
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
Google Workspace MCP ServerCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
The fastest path is the five-step Workspace MCP Quick Start, which walks through installation, Google OAuth setup, server startup, client connection, and validation.
You will need Python 3.10 or newer, uv/uvx, and a Google Cloud project with OAuth credentials. For a confidential OAuth client, a basic modern HTTP setup looks like this:
export GOOGLE_OAUTH_CLIENT_ID="your-client-id"
export GOOGLE_OAUTH_CLIENT_SECRET="your-client-secret"
export MCP_ENABLE_OAUTH21=true
uvx workspace-mcp --transport streamable-http --tool-tier core
Streamable HTTP is the recommended transport for modern MCP clients, OAuth 2.1, and multi-user deployments. Claude Desktop, Claude on the web, and Claude Cowork can connect through a custom Connector; Claude Code, VS Code, MCP Inspector, and other compatible clients can connect directly to the HTTP endpoint. Stdio remains available as a legacy fallback.
Start with the core tool tier, move to extended or complete when you need more operations, or load only selected services with --tools. Public PKCE clients, reverse proxies, and hosted deployments require additional authentication settings, so use the Quick Start Guide for setup and the authentication documentation for production configuration.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"google workspace mcp server": {
"google_workspace_mcp": {
"command": "uvx",
"args": [
"workspace-mcp"
]
}
}
}
}McpServers
{
"google_workspace_mcp": {
"command": "uvx",
"args": [
"workspace-mcp"
]
}
}Integrates Google Workspace services like Calendar, Drive, and Gmail with AI assistants.
Full natural language control over Google Calendar, Drive, Gmail, Docs, Sheets, Slides, Forms, Tasks, Contacts, and Chat through all MCP clients, AI assistants and developer tools.Includes a full featured CLI & Code Mode for use with tools like Claude Code and Codex!
The most feature-complete Google Workspace MCP server, it can do things that Google's own tooling and the built in integrations with Claude and ChatGPT can't come close to. With multi-user support, rich fine-grained editing tools and the most extensive coverage of any Google Workspace tool in existence, Workspace MCP is in a different class.
By leveraging native OAuth 2.1, stateless deployment capability and external auth server & gateway passthrough auth support, it's also the only Workspace MCP you can host for your whole organization centrally & securely!
Workspace MCP connects AI assistants to all twelve major Google Workspace services - 120+ tools behind a single MCP server, with OAuth 2.1 multi-user auth, three progressive tool tiers, read-only mode, a full CLI, and stateless container deployment. It runs locally over stdio for legacy clients and remotely over streamable HTTP with full implementation of the latest MCP spec.
The README covers just enough to get you running, with extensive documentation on the website:
By default, this server sends no data anywhere except Google's APIs, on behalf of the authenticated user, using your own OAuth client credentials. There is no usage reporting, analytics, license server, or SaaS dependency outside optional OTel support for your own usage.
- Fully open source— every line is auditable in this repo
- Your OAuth client, your GCP project— credentials never leave your environment & you control scopes
- You control the network— deploy behind your reverse proxy, in your VPC, on your own terms
- Stateless mode— zero disk writes for locked-down container environments
- Sensitive path blocking— local file reads default to the managed attachment directory, andvalidate_file_path()still blocks.envfiles plus common home-directory credential stores such as~/.ssh/and~/.aws/even ifALLOWED_FILE_DIRSis broadened
Full dependency tree inpyproject.toml, pinned inuv.lock.
- Use commercially without restriction— build products, sell services, deploy internally
- Fork, embed, redistribute— MIT requires only attribution
- No CLA— contributions remain under MIT
- No built-in telemetry to disclose— optional tracing is off unless you configure it
- No network effects— the server never contacts any endpoint you didn't configure
- Standard dependency licenses— MIT, Apache 2.0, and BSD throughout the dependency chain; no copyleft, no AGPL
Each page lists every tool with its tier, parameters, required scopes, and example prompts. Thecomplete referencecovers all twelve in one place.
💬Google Chatneeds a one-time Chat app configuration and a Workspace account - see theChat setup FAQ.
Set credentials → pick a launch command → connect your client. Full walkthrough with screenshots:workspacemcp.com/quick-start
You'll need an OAuth client fromGoogle Cloud Consolewith the APIs enabled for the services you plan to use - thequick start guidewalks through it in about five minutes.
# 1. Credentials export GOOGLE_OAUTH_CLIENT_ID="..." export GOOGLE_OAUTH_CLIENT_SECRET="..." # 2. Launch - pick a tier uvx workspace-mcp --tool-tier core # essential tools uvx workspace-mcp --tool-tier extended # core + management ops uvx workspace-mcp --tool-tier complete # everything # Or cherry-pick services uvx workspace-mcp --tools gmail drive calendar
# 1. Credentials - MCP clients connect with PKCE and no # secret, but Google still requires one server-side export MCP_ENABLE_OAUTH21=true export GOOGLE_OAUTH_CLIENT_ID="..." export GOOGLE_OAUTH_CLIENT_SECRET="..." export WORKSPACE_MCP_PORT=8000 export GOOGLE_OAUTH_REDIRECT_URI="http://localhost:${WORKSPACE_MCP_PORT}/oauth2callback" export OAUTHLIB_INSECURE_TRANSPORT=1 # 2. Launch - OAuth 2.1 requires HTTP transport uvx workspace-mcp --transport streamable-http --tool-tier core
Tool tierskeep context windows lean:coreis the essential set,extendedadds management operations,completeloads everything. Combine with--tools <service> ...,--read-only, or per-service--permissions, and subtract individual tools with--disabled-tools <name> ...- details in theserver modes docs.
Claude Desktop, web & mobile- run the server in HTTP mode and add it as aConnector(Settings → Connectors → Add custom connector). This is the recommended path; theConnector guidehas step-by-step screenshots. Legacy stdio configuration remains available for clients without Connector support - see theFAQ.
# Start the server in HTTP mode, then: claude mcp add --transport http workspace-mcp http://localhost:8000/mcp # Optional: install the bundled skill for better Workspace tool routing ln -s "$(pwd)/skills/managing-google-workspace" ~/.claude/skills/managing-google-workspace
ChatGPT- connect via Developer Mode with theChatGPT guide.
VS Code, LM Studio, Open WebUI, and everything else- any MCP client works over streamable HTTP (recommended) or stdio. Client-specific walkthroughs live in theguidesandFAQ.
workspace-clilists and calls tools against a running server with encrypted, disk-backed OAuth token caching - authenticate once, script forever:
uv run workspace-cli list uv run workspace-cli call search_gmail_messages query="is:unread" max_results=5
Install globally withuv tool install .from this repo. ⚠️ Don't useuvx workspace-cli- an abandoned PyPI package squats that name.
Everything you need to run this in production lives in two places. Thedocumentationcovers auth modes and server configuration:
- OAuth 2.1 multi-user auth- bearer tokens, required for remote or shared HTTP endpoints
- Stateless container mode- zero disk writes for locked-down deployments
- OAuth proxy storage backends- memory, disk, or Valkey/Redis for distributed setups
- External OAuth provider mode- bring your own auth server, validate bearer tokens only
- Service accounts with domain-wide delegation- per-request user impersonation with an optional domain allowlist
- OpenTelemetry tracing- optional, off unless you configure an OTLP endpoint
- Docker-docker build -t workspace-mcp . && docker run -p 8000:8000 workspace-mcp
TheAdvanced Deployment guidecovers self-hosting specifics: reverse proxy setup withWORKSPACE_EXTERNAL_URL(including the nginxOrigin: nullconsent workaround, theWORKSPACE_MCP_ALLOW_NULL_ORIGIN_CONSENTescape hatch, and theReferrer-Policypitfall), origin validation and VS Code webview allowlisting, credential store backends (local directory or GCS with CMEK enforcement), and thecomplete environment variable reference.
By default this server sends no data anywhere except Google's APIs, using your own OAuth client credentials - no usage reporting, analytics, license server, or SaaS dependency. MIT licensed with no CLA, no dual licensing, and no copyleft in the dependency chain. The full security posture - scope minimization, sensitive-path blocking, stateless mode - is documented atworkspacemcp.com.
A few things worth internalizing before you connect an LLM to your email:
- Prompt injection is real.Emails, docs, and events can contain hidden instructions. Only connect trusted data to an LLM, and be deliberate about which write tools you enable.
- Never commit.env,client_secret.json, or.credentials/to source control.
- Local file reads are sandboxedto the managed attachment directory. Broaden withALLOWED_FILE_DIRSonly if you trust the client and its data sources;.env,~/.ssh/,~/.aws/, and similar paths are always blocked.
- Production**deployments should use HTTPS and OAuth 2.1.
uv sync --group dev # install deps uv run ruff check . # lint uv run pytest # test
Single-file service modules live ing<service>/, tools are registered with@server.tooldecorators, and tiers are defined incore/tool_tiers.yaml. PRs welcome.
MIT - seeLICENSE. The license is 21 lines and says what it means.
Integrate Google services like Gmail, Calendar, Drive, and Tasks with MCP.
(MCP) server for Google Workspace. Drive, Gmail, Calendar, Sheets, Docs, Tasks and People via AI agents.
Interact with Google Workspace services like Gmail and Google Calendar.
Manage Gmail, Calendar, Drive, and Contacts through Google Workspace APIs using OAuth 2.0.
An MCP server for interacting with Google Workspace services like Gmail and Calendar.
Interact with Google products, including Gmail and Calendar.
A comprehensive MCP server for managing Google Workspace services like Calendar, Contacts, and Gmail using OAuth2 authentication.
Multi-account Google MCP server for Claude Code — Gmail, Drive, Calendar, Sheets, Docs, Contacts, Search Console. 83 tools with OAuth2 multi-account switching.
A command-line tool to fetch Google Calendar schedules and convert them into custom prompts or text snippets using a template engine.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
