Gmail Agent

What gmail-agent MCP server does

The gmail-agent MCP server gives local AI agents access to Gmail through both an MCP interface and a command-line application. It can search messages with Gmail query syntax, retrieve individual messages or threads as plain text, inspect labels and drafts, and work with attachments. HTML email is converted to text when messages are read.

Attachment handling is a central use case. Agents can list attachment metadata, download selected files, download attachments from every message matching a query, or extract text from PDF and text files without writing them to disk. Downloaded filenames are sanitized and existing files are not overwritten; a duplicate receives a numbered filename.

Mail operations include sending, replying, replying to all recipients, forwarding, and creating or managing drafts. The server also supports label creation and maintenance, applying or removing labels, marking messages read or unread, starring, archiving, trashing, and untrashing. Permanent deletion requires an explicit option and a full-access login.

How it works

The package runs on the user’s machine and calls the Gmail API directly. Authentication uses an OAuth client created in Google Cloud, rather than a hosted intermediary. During setup, the user selects an access level ranging from read-only to full access. The available tools follow that granted scope, so write operations are not exposed when the login does not permit them.

The MCP entry point uses stdio and is started with gmail-agent mcp. The same package provides commands such as gmail-agent search, gmail-agent status, and setup commands for shell-oriented agents. CLI commands can return JSON, including identifiers for messages or resources that were created.

Every write command supports a dry-run mode. Before changing Gmail, the command can print the API request and, for outgoing mail, the generated MIME message. This provides a way to inspect a send, reply, draft, label change, or other mutation before execution.

Setup and configuration

Install with uv tool install gmail-agent or use pipx, then run gmail-agent setup. The guided setup helps create or select a Google Cloud project, enable the Gmail API, configure an OAuth client, and sign in. Python 3.11 or newer is required, along with uv or pipx for the documented installation paths.

The OAuth client must be a Desktop app client. An existing client file can be supplied with --client-file, and an existing Google Cloud project can be selected with --project. Run gmail-agent status to view the logged-in account and access level.

To use the gmail-agent MCP server with an MCP client, configure that client to launch gmail-agent mcp. The README documents connections for Claude Code, Codex, Gemini CLI, VS Code, Cursor, and Claude Desktop. No hosted account or third-party relay is required.

Tools and capabilities

Supported operations include:

• Search Gmail messages with pagination and Gmail search syntax.
• Read messages and threads as text.
• List, download, and locally extract text from attachments.
• Send, reply, reply-all, and forward messages, including attachments where supported.
• Create, list, inspect, update, send, and delete drafts.
• Create, rename, delete, apply, and remove labels.
• Mark messages read or unread, star, archive, trash, and untrash messages.

The gmail-agent MCP server also supports selecting attachments by filename or part ID, and can return the paths of downloaded files. Forwarding preserves the original attachments according to the documented behavior.

Limitations and notes

The package covers Gmail only; it does not provide Drive, Calendar, or Docs operations. It does not currently support Gmail filters, sending from an alias, Gmail signatures, or inline images in outgoing mail. Setup requires a user-managed Google Cloud OAuth client and an interactive login, so it is not a no-setup hosted connector.

The MCP transport documented here is stdio, not a team-oriented HTTP service. Read-only access is available, but capabilities depend on the selected OAuth scope. Deletion defaults to trash, while permanent deletion is guarded by both the --allow-delete option and a full-access login.