MCP
Google Workspace MCP
An MCP server and CLI that lets an agent use Gmail, Calendar, Docs, Sheets, Drive, and other Workspace services.
taylorwilsdon/google_workspace_mcp is an MIT-licensed MCP server and CLI. It lets an agent use Gmail, Calendar, Docs, Sheets, Slides, Chat, Forms, Tasks, Search, and Drive. That is the scope of your Google account.
Start with a test account or the narrowest OAuth scopes, not with mail and Drive for a whole organization. Require a person to confirm before a message is sent or a sharing setting changes.
Mentioned by:
- @beamnxw mentioned this project on 15 September 2026 (633 likes and 105 reposts, captured 15 November 2026).
This page is a guide, not the original text.
What problem it solves
Google Workspace MCP (repository taylorwilsdon/google_workspace_mcp, PyPI package workspace-mcp) lets a coding agent call Workspace services such as Gmail, Calendar, Drive, Docs, Sheets, Slides, Forms, Tasks, Contacts, and Chat through MCP. It acts on a Google account you have authorized, not only on local files.
Official docs separate this self-hosted server from a hosted product called Workspace MCP Cloud. This page covers only the open-source, self-hosted path: you create an OAuth client in your own Google Cloud project, and the server uses those credentials to call Google APIs. Do not apply the hosted product’s setup steps to a local install.
Who it is for
It is for people who already have an MCP client such as Claude Code, Claude Desktop, or VS Code, and who want an agent to read or change their Workspace data after an explicit grant. The project is MIT-licensed and independent. It is not affiliated with Google.
It is a poor first install on a company’s production mailbox or a shared Drive. Scopes can include sending mail and writing to Calendar or Drive, so a bad tool call is costly. Start with a test account, or with the narrowest scopes you can live with.
How to install it
Checked on 15 November 2026 (Asia/Shanghai) against the repository README and the official Quick Start (the page says it is synced with v2.5.0, dated 14 November 2026).
The Python requirement is not identical across official sources. The README badge and pyproject.toml say Python 3.11 or newer. The Quick Start says Python 3.10 or newer, plus uv. This page does not invent a single number. Install against the source you are following, and check python3 --version on your machine.
Create an OAuth client in the Google Cloud Console and enable only the APIs you plan to use. The Quick Start distinguishes client types clearly: Desktop application is for local CLI and stdio setups; Web application is for hosted HTTP, reverse proxies, and browser clients, and its authorized origins and redirect URIs must match the public URL people authenticate against. The official local-HTTP example sets OAUTHLIB_INSECURE_TRANSPORT=1. That setting does not belong in production.
export GOOGLE_OAUTH_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export GOOGLE_OAUTH_CLIENT_SECRET="your-client-secret"
# Start with the core tier and widen later if needed
uvx workspace-mcp --tool-tier core
# Streamable HTTP is recommended for modern clients; the default is http://localhost:8000/mcp
uvx workspace-mcp --transport streamable-http --tool-tier coreMulti-user OAuth 2.1 requires HTTP transport and cannot be combined with --single-user:
export MCP_ENABLE_OAUTH21=true
uvx workspace-mcp --transport streamable-http --tool-tier coreYou can also load a subset of services with --tools gmail drive calendar, or restrict access with --read-only or --permissions. Official docs give examples such as --permissions gmail:send drive:readonly. --read-only requests readonly scopes and hides write tools. It is mutually exclusive with --permissions.
Claude Code
Start the HTTP server first. The repository README gives this command:
claude mcp add --transport http workspace-mcp http://localhost:8000/mcpThe Quick Start from the same period names the server workspacemcp. This page does not pick a winner. Follow the page you are using, then confirm the connection in the client’s MCP list. A bundled skill at skills/managing-google-workspace is optional.
Claude Desktop
Official docs recommend a custom connector: Settings → Connectors → Add custom connector, then paste your server URL. Step-by-step screenshots are in the connector guide. stdio remains a fallback for clients without connectors.
VS Code
The official Quick Start adds this to .vscode/mcp.json or a user-level mcp.json:
{
"servers": {
"workspacemcp": {
"type": "http",
"url": "http://localhost:8000/mcp"
}
}
}The workspace-cli tool can list and call registered tools. Install it from the repository with uv tool install .. Official docs explicitly warn against uvx workspace-cli, because an abandoned package occupies that name on PyPI.
A worked example
The steps below are a check written for this page, not a canned official phrase. They were not run against a live account, so this page does not invent a message list.
- Finish OAuth with a test account. Enable only the APIs you need, and prefer
coreor--read-onlyfor the first run. - In a connected client, send:
List my five most recent unread Gmail messages. Do not send, delete, or change labels. - If you installed the CLI, you can also run:
workspace-cli call search_gmail_messages query="is:unread" max_results=5- Check the subjects against Gmail in the browser. If the tool list is wider than you expected, inspect the tier and permission flags before you continue.
Common pitfalls
- Scopes that are too wide.
--permissionsand--read-onlychange both the Google scopes requested and the tools the model can see. Gmailsendorfull, and Drive or Calendarfull, can change real data. Official security guidance also warns that email, docs, and events can carry prompt-injection text, so enable write tools deliberately. - The wrong OAuth client type, or a redirect URI that does not match the URL people actually use. The Quick Start is explicit about Desktop versus Web application. Web clients need matching origins and an
/oauth2callbackredirect. - Deleting a calendar event that has attendees. Issue #1312 (still open on 15 November 2026) notes that
manage_eventdelete can still remove a meeting with guests even whensend_updates="none". Confirm with a person before deleting or changing sharing. - Secrets committed to git. Official docs say not to commit
.env,client_secret.json, or.credentials/. Production deployments should use HTTPS and OAuth 2.1. - Python version mismatches. If
uvxfails to start, check whether you followedpyproject.toml’s 3.11+ requirement or the Quick Start’s 3.10+ requirement, then look at the Python version on your machine. Do not average the two.
FAQ
Is this the same as Workspace MCP Cloud?
No. They are different setup paths. Cloud is a hosted service on the official site, with its own plans and onboarding. This page describes the self-hosted server in the open-source repository, using your own Google Cloud OAuth client. Do not apply the Cloud FAQ to uvx workspace-mcp.
How do I keep access as narrow as possible?
Official docs suggest starting with --tool-tier core, then --tools to load only the services you need. Add --read-only if you do not need writes, or --permissions for per-service levels such as gmail:readonly. Those two flags cannot be combined. --disabled-tools can also remove a single tool.
Do I need a paid Google Workspace account?
The README says the server supports free Google accounts and Google Workspace plans, with some apps such as Chat having expanded options on Workspace plans. This page did not independently verify plan-by-plan features. Follow Google’s docs and the project docs. The MCP server itself is MIT-licensed open source.
Why do tool calls still fail after I authorize the app?
Confirm that the matching Google APIs are enabled in the same project, that the OAuth client type and redirect URI match the transport you are using, and that the loaded tier actually includes the tool. Issue #1195 also recorded a case where an OAuth 2.1 authorization request without scope received only identity scopes, after which tool calls failed (that issue is now closed).
Can I run workspace-cli with uvx?
Official docs say not to. Install it from the repository with uv tool install ., or run uv run workspace-cli inside the repo. uvx workspace-cli may resolve to an abandoned package of the same name on PyPI.
Sources and license
taylorwilsdon/google_workspace_mcp is licensed under MIT. This page follows the README, the Quick Start, and the permissions section in the docs as of 15 November 2026, rewritten for CQBase — Context & Query Base. If the install commands, the Python requirement, or the permission flags change, follow those official pages.
In this category
- MCP
Awesome MCP Servers
The MCP server list people most often cite, under MIT.
punkpeye - MCP
MCP reference servers
Reference servers from the protocol organization, for seeing the smallest shape of an MCP server.
modelcontextprotocol - MCP
Context7
An MCP that feeds current library docs to an agent so it writes against the API you have.
upstash