cqbase.net · English & Chinese

CQBase

Context & Query Base

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 core

Multi-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 core

You 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/mcp

The 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.

  1. Finish OAuth with a test account. Enable only the APIs you need, and prefer core or --read-only for the first run.
  2. In a connected client, send: List my five most recent unread Gmail messages. Do not send, delete, or change labels.
  3. If you installed the CLI, you can also run:
workspace-cli call search_gmail_messages query="is:unread" max_results=5
  1. 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. --permissions and --read-only change both the Google scopes requested and the tools the model can see. Gmail send or full, and Drive or Calendar full, 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 /oauth2callback redirect.
  • Deleting a calendar event that has attendees. Issue #1312 (still open on 15 November 2026) notes that manage_event delete can still remove a meeting with guests even when send_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 uvx fails to start, check whether you followed pyproject.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.

Subscribe to CQBase Weekly

One email a week with newly catalogued public AI skills, prompts, MCP servers, and methods. Unsubscribe at any time. We will not hand your address to a third party for their marketing.