Gmail

What the Gmail MCP server does

The Gmail MCP server exposes Gmail account and mailbox operations through MCP. Agents can retrieve the signed-in user's profile, search messages or threads, read individual messages, and inspect every message in a thread. Thread search and retrieval are identified as the preferred options when working with conversations.

Email-management operations include sending messages, forwarding messages, applying or removing labels, archiving inbox items, moving messages or threads to trash, restoring them, and permanently deleting them. Batch message operations support bulk label changes and permanent deletion.

Draft workflows cover listing, reading, creating, updating, sending, and deleting drafts. The server also exposes label listing and retrieval, along with additional Gmail operations documented by the project for attachments, filters, and vacation auto-reply settings.

How it works

The Gmail MCP server acts as an OAuth proxy between an MCP client and Google. The client connects to the MCP endpoint, while the server advertises OAuth authorization metadata, registers clients, redirects users to Google, and handles the callback and token exchange. Authenticated requests arriving at /mcp are sent to the Gmail API with the bearer token.

The documented architecture says the server does not retain tokens or application state; it passes OAuth traffic between the client and Google. Gmail API access is based on scopes for reading, sending, and modifying mailbox content. Modification access covers actions such as archiving, changing labels, and moving messages to trash.

Setup and configuration

Create a Google Cloud project or use an existing one, enable the Gmail API, configure the OAuth consent screen, and create an OAuth client ID for a web application. Add http://localhost:3000/callback as an authorized redirect URI, then retain the generated client ID and client secret.

Start the server with the Google credentials and HTTP transport configured:

GOOGLE_CLIENT_ID='your-client-id' \
GOOGLE_CLIENT_SECRET='your-client-secret' \
MCP_TRANSPORT=http \
npm start

The default address is http://localhost:3000. Set PORT to use another port, such as 3001. Once it is running, use the project's installation instructions to generate MCP client configuration for the server endpoint.

Tools and capabilities

• Search and list messages or threads.
• Read messages and complete threads.
• Send, forward, create, update, and send drafts.
• Add or remove labels, archive messages, and perform bulk label changes.
• Trash, restore, or permanently delete messages and threads.
• List and inspect Gmail labels.
• Retrieve attachments and manage documented filters and vacation settings.

Limitations and notes

The server requires Google OAuth credentials and Gmail API access. Actions that change mailbox content need the corresponding Gmail modification scope, while sending requires the send scope. Permanent deletion and sending are available as separate tools, so an agent configuration should account for their different effects.

The message-listing tool is available, but the project recommends thread listing for conversation-oriented searches. Likewise, thread retrieval is recommended when the agent needs the complete conversation rather than one message.

The provided setup uses a localhost callback and HTTP transport.