Gmail MCP Server: Setup Guide, Use Cases & Limitations

What Is Gmail MCP Server?

Gmail MCP Server is a Model Context Protocol server that connects Claude Desktop to your Gmail account, enabling read, search, and send operations directly from the assistant interface. It is maintained by gongrzhe and published as an open-source project on GitHub.

Quick Facts

What You Can Do With It

• Email search: Query your inbox using natural language or Gmail-style filters to locate specific messages or threads.
• Draft creation: Compose and save email drafts without leaving your Claude Desktop session.
• Inbox triage: Review and categorize incoming messages to prioritize responses.
• Email automation: Chain read and send operations to handle repetitive email workflows with minimal manual input.

How to Set It Up

Prerequisites: You need a Google account and OAuth credentials configured for the Gmail API. Before running the server, enable the Gmail API in your Google Cloud Console, create OAuth 2.0 credentials (Desktop app type), and download the credentials.json file.

Step 1 — Run the setup command:

npx mcp-gmail
On first run, this will prompt you through OAuth authorization in your browser and cache a token locally.

**Step 2 — Add the server to your Claude Desktop config:**

Open `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or the equivalent path on your OS, and add the following block under `mcpServers`:

```json
{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": ["mcp-gmail"]
    }
  }
}

Step 3 — Restart Claude Desktop to load the new server configuration. If authorization was successful, Gmail tools will appear available in your session.

Works Best With

Gmail MCP Server is documented as compatible with Claude Desktop. It is not listed as tested or supported with Claude Code or other MCP clients. If you attempt to use it outside Claude Desktop, expect untested behavior and possible authentication flow issues, as the OAuth redirect is designed for a local desktop environment.

Known Limitations

• OAuth setup is manual: You must configure Google Cloud credentials yourself before the server is functional. There is no built-in credential provisioning.
• Token storage: Credentials are cached locally. If the token expires or is revoked, you will need to re-authorize manually.
• Gmail API rate limits apply: Google enforces per-user and per-project quota limits on the Gmail API. High-volume automation may hit these limits. Check Google’s quota documentation for current thresholds.
• Scope exposure: Granting Gmail access means the server operates with the permissions you authorize. Review the requested OAuth scopes before approving access.
• No calendar or Drive integration: This server is scoped to Gmail only. Cross-product Google Workspace operations are out of scope.
• Windows path behavior for the config file may differ — verify the correct location for claude_desktop_config.json on your OS.

Community Resources

• GitHub Repository — primary source for setup docs and updates
• GitHub Issues — report bugs or check known problems
• MCP Servers – r/ClaudeAI — community discussions on Claude Desktop MCP integrations
• Anthropic Discord — #mcp channel for general MCP server troubleshooting