Gmail MCP

What @klodr/gmail-mcp MCP server does

The @klodr/gmail-mcp MCP server gives MCP-compatible AI assistants access to selected Gmail operations through the Gmail API. Its surface covers messages, threads, labels, filters, attachments, drafts, replies, and forwards. Depending on the granted authorization scopes, an assistant can search and read mail, compose or send messages, manage labels and filters, inspect conversations, and work with attachments.

Thread-aware operations include retrieving a thread, listing inbox threads, and getting an inbox view with threads. Message handling includes reply-all support, send-as aliases, recipient pairing, and display of Cc and Bcc fields. The server also supports batch modifications and deletion, with retry handling described in the project material.

How it works

The package runs as an MCP server and mediates Gmail API calls through tools selected according to the OAuth scopes available to it. The --scopes option supports least-privilege authorization, while the exposed tool list is filtered to match those permissions. OAuth handling includes a loopback callback protected with state and PKCE, and credentials files are written with restrictive permissions.

Security controls are applied inside the process rather than relying only on operator behavior. These include input sanitization, bounds on batch and result sizes, rate and write caps, recipient pairing, sender-alias checks, and audit logging. Download destinations and attachment sources are confined by path jails, with symlink-safe write checks. Exported HTML blocks scripts, frames, forms, and remote resources unless explicitly allowed.

Setup and configuration

The documented installation model is a single npx package install. Authentication uses Gmail API OAuth credentials; a gcp-oauth.keys.json file in the project directory is imported during the authentication flow rather than on ordinary server startup. The server supports the --scopes flag to select the required Gmail permissions.

Recipient pairing can be enabled with GMAIL_MCP_RECIPIENT_PAIRING. When active, sends, replies, forwards, and drafts are restricted to paired addresses. The pairing list must be changed through the MCP client with human confirmation or with the package’s npx @klodr/gmail-mcp pair add command.

Tools and capabilities

The @klodr/gmail-mcp MCP server supports capabilities including:

• Reading, searching, sending, and drafting Gmail messages.
• Replying in existing threads, including reply-all behavior.
• Managing labels and filters, with forwarding filters refused.
• Retrieving threads and thread-based inbox views.
• Downloading messages as JSON, EML, text, or HTML.
• Downloading one attachment or all attachments, optionally as a ZIP.
• Performing batch message updates and deletions.
• Sending from a permitted Gmail send-as alias.

Tool annotations identify read-only, destructive, and idempotent operations for MCP clients.

Limitations and notes

The server only exposes operations allowed by the OAuth scopes granted to it, so missing permissions can remove tools from the available list. Recipient pairing is optional, but when enabled it constrains outbound message actions and cannot be expanded by the model through Gmail. A from value that is not an available send-as alias is rejected when the account’s alias list can be read.

Downloaded files are marked as originating from the internet where the platform supports that behavior. The project is a hardened fork of earlier Gmail MCP implementations, so behavior and safeguards may differ from upstream projects. Use the @klodr/gmail-mcp MCP server when Gmail access, scoped authorization, and guarded outbound or filesystem operations are all relevant to the workflow.