Gmail MCP Server

What is Gmail MCP Server?

A Java-based Model Context Protocol (MCP) server that integrates with Gmail to enable natural language email queries via Claude Desktop. It exposes tools to search emails by topic and read email content, using the Gmail API with secure OAuth2 authentication.

How to use Gmail MCP Server?

Build the project with mvn clean install, then run java -jar target/gmail-mcp-server-1.0-SNAPSHOT.jar. On first run, authenticate via OAuth2 in the browser; tokens are saved to ~/.gmail-mcp/tokens. Configure Claude Desktop by adding an entry with the java command and JAR path in the MCP configuration file.

Key features of Gmail MCP Server

• Search emails by topic, sender, or date using Gmail query syntax
• Retrieve full email content (subject, sender, body) by ID
• Secure OAuth2 authentication with minimal gmail.readonly scope
• Communicates with Claude Desktop via Stdio and JSON-RPC 2.0
• Robust error handling, logging, and input validation

Use cases of Gmail MCP Server

• Ask Claude Desktop to find emails about a project deadline from the last month
• Query emails from a specific sender about conference planning
• Read the full content of a particular email by providing its ID
• Search across Gmail using natural language instead of manual filters

FAQ from Gmail MCP Server

What dependencies are required?

Java 17, Maven, a Google Cloud project with the Gmail API enabled and OAuth2 credentials, and Claude Desktop.

How are OAuth2 tokens stored?

Tokens are saved to ~/.gmail-mcp/tokens for persistent authentication across runs. This file should be excluded from version control.

What is the email search limit?

The server limits search results to 10 emails to respect Gmail API rate limits of 250 queries per minute.

What transport protocol does the server use?

It runs in Stdio mode, communicating with Claude Desktop via JSON-RPC 2.0.

How do I resolve authentication errors?

Ensure credentials.json is in src/main/resources/ and delete ~/.gmail-mcp/tokens to re-authenticate if tokens become invalid.