How do I install Gmail?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Gmail need an API key?

No required environment variable is listed on this record.

When was Gmail last checked?

Last checked 2026-10-27. MCP server providing read-only Gmail tools for AI assistants like Claude Code

Gmail MCP 服务器

接入你的智能体

添加此服务器

Install from the publisher. Not a PlugMCP endpoint.

在 PlugMCP 上运行

用我们的密钥与日志托管一份副本。

No packaged release in the registry yet. Follow the repository README.

RepositoryPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

在 PlugMCP 上运行

用我们的密钥与日志托管一份副本。

这是你新建的服务器，不是此条目的官方端点。若要用发布方的 URL 与凭证，请使用上方安装面板。

启动

Server facts

Local

Transport: stdio
License: MIT
Last checked: 2026-10-27

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

Gmail MCP Server

A Model Context Protocol (MCP) server that provides read-only Gmail access to AI assistants like Claude Code. Built in Java 21 using the official MCP Java SDK.

Features

Tool	Description
`list_emails`	List recent emails with optional query and label filter
`read_email`	Read the full content of an email by message ID (includes attachment metadata)
`search_emails`	Search emails using Gmail search syntax
`get_attachment`	Fetch attachment content by message ID and attachment index
`list_labels`	List all Gmail labels

All access is read-only (GMAIL_READONLY scope). The server cannot send, modify, or delete emails.

Attachments are discovered via read_email (which includes an attachments array with metadata) and fetched individually via get_attachment:

Text attachments (text/*) return decoded content inline
Image attachments (image/*, up to 10 MB) are returned as inline ImageContent for visual analysis
Other binary attachments (PDF, documents, etc.) are saved to ~/.gmail-mcp/attachments/<messageId>/ and the file path is returned

Prerequisites

Java 21+
Maven 3.6+
A Google Cloud project with the Gmail API enabled
OAuth 2.0 credentials (Desktop application type)

Setup

1. Google Cloud credentials

Go to the Google Cloud Console
Create a project (or select an existing one)
Enable the Gmail API under APIs & Services
Go to Credentials > Create Credentials > OAuth client ID
Select Desktop app as the application type
Download the JSON file and save it as ~/.gmail-mcp/client_secret.json

2. Build

git clone https://github.com/wrxck/gmail-mcp.git
cd gmail-mcp
mvn clean package

This produces a single uber-jar at target/gmail-mcp-1.3.0.jar.

3. Authenticate

java -jar target/gmail-mcp-1.3.0.jar --auth

This opens your browser for Google OAuth consent. After authorizing, credentials are saved to ~/.gmail-mcp/tokens/ and automatically refreshed on expiry. You only need to do this once.

4. Register with Claude Code

claude mcp add --scope user --transport stdio gmail -- \
  java -jar /path/to/gmail-mcp-1.3.0.jar

Restart Claude Code. The 4 Gmail tools will be available immediately.

Usage examples

Once registered, you can ask Claude:

"Check my recent emails"
"Search for emails from [email protected] about the project proposal"
"Read email <message-id>"
"What labels do I have?"
"Find unread emails in my inbox from this week"

Security

Email content is untrusted third-party data that gets returned directly into an LLM's context. A malicious email could contain text designed to manipulate the agent into taking unintended actions. This server applies defense-in-depth mitigations:

Random content boundaries — Each tool response generates a cryptographically random boundary string (via SecureRandom). Untrusted fields (from, subject, snippet, body, filename, content) are wrapped with this boundary so the LLM can distinguish email data from system structure. Since the boundary is unpredictable, an attacker cannot embed it in their email to escape the content region.
Security context preamble — Every email tool response includes a leading text block explaining the boundary token and instructing the LLM to treat bounded content as data only.
Tool description warnings — The list_emails, read_email, search_emails, and get_attachment tool descriptions explicitly warn that returned content is untrusted.
Body truncation — Email bodies exceeding 50,000 characters are truncated with a [TRUNCATED] indicator to prevent oversized payloads from overwhelming context. Attachment content is truncated at 100,000 characters.
Typed attachment handling — text/* attachments return decoded content inline. image/* attachments (up to 10 MB) are returned as ImageContent for vision analysis. All other binary attachments are saved to ~/.gmail-mcp/attachments/ with sanitized filenames, and the file path is returned. Filenames from emails are sanitized to prevent path traversal attacks.

Architecture

Claude Code  <--stdio (JSON-RPC)-->  gmail-mcp.jar  <--HTTPS-->  Gmail API
                                          |
                                    ~/.gmail-mcp/
                                      client_secret.json
                                      tokens/StoredCredential

Transport: stdio (Claude Code spawns the server as a subprocess)
OAuth: GoogleAuthorizationCodeFlow with FileDataStoreFactory handles token persistence and automatic refresh
Logging: All logs go to stderr (stdout is reserved for MCP JSON-RPC)

Configuration

Credentials are stored in ~/.gmail-mcp/ with restricted permissions (rwx------):

~/.gmail-mcp/
  client_secret.json    # OAuth client credentials (you provide this)
  tokens/               # Stored OAuth tokens (auto-managed)
    StoredCredential
  attachments/           # Saved binary attachments (auto-managed, rwx------)
    <messageId>/
      <sanitized-filename>

Development

# Build
mvn clean package

# Run tests
mvn test

# Run auth flow
java -jar target/gmail-mcp-1.3.0.jar --auth

# Run server (blocks on stdio — use with Claude Code or an MCP client)
java -jar target/gmail-mcp-1.3.0.jar

Project structure

src/main/java/com/gmail/mcp/
  GmailMcpServer.java    # Main class, MCP tool definitions
  GmailAuth.java          # OAuth flow, credential management
  GmailClient.java        # Gmail API wrapper
  ContentSanitizer.java   # Prompt injection mitigations

src/test/java/com/gmail/mcp/
  ContentSanitizerTest.java    # Boundary wrapping, truncation, sanitization
  ResponsePipelineTest.java    # End-to-end response pipeline (email vs label tools)
  GmailClientTest.java         # HTML stripping, base64 decoding, body extraction
  GmailMcpServerTest.java      # Argument parsing

License

MIT

Gmail

添加此服务器

用我们的密钥与日志托管一份副本。

Server facts

Tools

Questions

How do I install Gmail?

Does Gmail need an API key?

What transport does Gmail use?

When was Gmail last checked?

Documentation

Gmail MCP Server

Features

Prerequisites

Setup

1. Google Cloud credentials

2. Build

3. Authenticate

4. Register with Claude Code

Usage examples

Security

Architecture

Configuration

Development

Project structure

License