How to Connect Gmail to Claude Code (And Why You Should Start Read-Only)

Connecting your email to an AI agent is a powerful workflow shift. With the right MCP server, Claude Code can search for receipts, draft replies, and triage your inbox. But email is your most sensitive data. Here’s a practical guide to the available servers and how to implement them with a security-first approach.

The Server Landscape: From Google's Endpoint to Focused Tools

You have several options, each with different trust and scope models.

Google's Official Workspace MCP Endpoint is the first-party option. You connect to https://workspace-developer.goog/mcp. The major benefit is that no third-party code touches your credentials. The trade-off is sparse documentation compared to community projects.

The Community Standard: taylorwilsdon/google_workspace_mcp
With over 1,700 stars, this is the most popular server. It provides access to 12 Google services and over 100 tools. For Gmail, it includes search, get content, send, reply, create draft, and label management. Crucially, it offers a three-tier permission system (Core/Extended/Full), allowing you to start with a read-only scope. To install it, you typically clone the repo and run its setup script, which will guide you through OAuth.

The Focused Alternative: MarkusPfundstein/mcp-gsuite
If you only need Gmail and Calendar, this 477-star server is a compelling choice. It requests a narrower OAuth scope, improving your security posture. It offers 6 core Gmail tools: query, get, create draft, delete draft, reply, and save attachments. Note: It requires Python 3.13+. Install via pip: pip install mcp-gsuite.

Installation & Configuration: The Security-First Workflow

1. Always Start Read-Only. Configure your claude_desktop_config.json to use the most restrictive scope first. For taylorwilsdon/google_workspace_mcp, this means the "Core" tier. This lets Claude Code search and read emails but not send, delete, or modify labels.
2. Use a Dedicated Google Project. When going through OAuth, don't use your default credentials. Create a new project in the Google Cloud Console specifically for Claude Code access. This makes permission auditing and revocation straightforward.
3. Configure Your claude_desktop_config.json. Here’s a minimal example for a local server:

   {
     "mcpServers": {
       "google-workspace": {
         "command": "python",
         "args": [
           "/path/to/google_workspace_mcp/server.py"
         ],
         "env": {
           "SCOPE_LEVEL": "CORE"
         }
       }
     }
   }
   

The Critical Security Trade-Offs

• OAuth Scope Creep: Most servers request gmail.modify (read + write + send + delete) by default. You must explicitly choose a narrower scope during setup.
• Token Storage: Refresh tokens are stored in local files (like token.json). A compromise of your machine means a compromise of your email. Consider using your OS's encrypted credential store if the server supports it.
• The Send Permission is Permanent: A hallucinated instruction that sends an email to the wrong person cannot be undone. Only enable send capabilities after extensive testing in draft-only mode.
• No Official MCP Reference Server: Except for Google's remote endpoint, all servers are community-built. You are trusting their code quality and maintenance.

Bottom Line: The technology is ready and the use cases are compelling. Begin with a read-only scope for a week. Use it to find old tickets, summarize threads, or locate attachments. Only consider enabling write permissions after you've built confidence in the agent's reliability and your own prompting precision.