Gmail MCP Server

About

Google does not publish a Gmail MCP server. The two repositories in the googleworkspace GitHub organisation — developer-mcp and dev-assist — are for building on Google Workspace APIs, not for reading your mail, so every Gmail MCP setup in circulation is community-built. The leading one by a wide margin is taylorwilsdon/google_workspace_mcp, a Python server published to PyPI as workspace-mcp that covers Gmail alongside eleven other Workspace services behind a single connection: Drive, Calendar, Docs, Sheets, Slides, Forms, Tasks, Contacts, Chat, Custom Search and Apps Script, 120+ tools in total. Gmail contributes fifteen of them across three loadable tiers — core is search_gmail_messages, get_gmail_message_content, get_gmail_messages_content_batch and send_gmail_message; extended adds threads, attachments, drafts, labels and filters; complete adds the batch label operations. Run it with `uvx workspace-mcp --tools gmail` to load Gmail only, or `--tool-tier core` to keep the tool schemas small. Auth is your own Google Cloud OAuth client — the server ships no credentials and sends nothing anywhere except Google's APIs — and `--read-only` is a real, documented switch. The server most third-party guides still name, GongRzhe/Gmail-MCP-Server (npm @gongrzhe/server-gmail-autoauth-mcp), was archived on 2025-08-06 and its npm package has not been published since; it still installs, which is why it keeps getting recommended.

Installation

uvx workspace-mcp --tools gmail

Setting up Gmail MCP

1. 1.Create your own OAuth client in Google Cloud

   The server ships no credentials — you bring a client ID and secret from your own Google Cloud project, with the APIs enabled for the services you plan to use. Use the Web Application client type if you are running it over HTTP; Desktop is only appropriate for a local stdio instance. Picking Desktop for a hosted setup is the single most common mistake, and it surfaces later as Error 400: redirect_uri_mismatch.

2. 2.Export the credentials and launch

   Two environment variables and one command. The tool tiers exist to keep tool schemas out of your context window: core is the essential set, extended adds management operations, complete loads everything.

   shell

   export GOOGLE_OAUTH_CLIENT_ID="..."
   export GOOGLE_OAUTH_CLIENT_SECRET="..."
   
   uvx workspace-mcp --tool-tier core

3. 3.Load only Gmail, if Gmail is what you want

   The default loads every service you have enabled. `--tools` cherry-picks, and it is the difference between a handful of tool schemas and 120+ on every request. `--read-only` and per-service `--permissions` narrow it further, and `--disabled-tools` subtracts individual tools by name.

   shell

   uvx workspace-mcp --tools gmail --read-only

4. 4.Connect the client over HTTP

   HTTP is the recommended transport; stdio remains for clients without Connector support. For Claude Desktop, web and mobile, run the server in HTTP mode and add it under Settings → Connectors → Add custom connector. For Claude Code it is one command against the running server.

   shell

   claude mcp add --transport http workspace-mcp http://localhost:8000/mcp

5. 5.For a shared or remote endpoint, turn on OAuth 2.1

   Multi-user and remote deployments need bearer-token auth rather than a single local credential file. MCP clients connect with PKCE and no secret, but Google still requires a client secret server-side, so both variables stay set. OAuth 2.1 requires the HTTP transport.

   shell

   export MCP_ENABLE_OAUTH21=true
   export WORKSPACE_MCP_PORT=8000
   export GOOGLE_OAUTH_REDIRECT_URI="http://localhost:${WORKSPACE_MCP_PORT}/oauth2callback"
   
   uvx workspace-mcp --transport streamable-http --tool-tier core

The fifteen Gmail tools, by tier

Tiers are defined in core/tool_tiers.yaml, so which of these load depends on the --tool-tier you launch with. Only the core four are loaded by default at that tier.

What people use it for

Which one should you use?

The choice here is not really between Gmail servers — it is between one maintained multi-service server and a set of frozen single-service ones.

Categories

Works With

Frequently Asked Questions

Related Guides