Gmail IMAP

You run a Gmail IMAP MCP Server that lets AI assistants read, search, and manage Gmail accounts through a Model Context Protocol interface. It supports multiple accounts, OAuth2 authentication, label management, attachment handling, and email composition, all exposed as MCP endpoints you can call from your preferred MCP client.

How to use

Connect your MCP client to the Gmail IMAP MCP Server using either the HTTP endpoint or the local stdio channel. Authenticate Gmail accounts once per user, then perform actions such as reading emails, searching with advanced queries, viewing unread messages, sending emails with optional attachments, and organizing messages by creating or moving between labels. You can download attachments, mark messages as read or unread, and summarize recent emails to get quick overviews. The system supports multiple Gmail accounts and uses OAuth2 for secure access.

How to install

Prerequisites: you need Python 3.12 or higher and a Google Cloud Project with the Gmail API enabled.

Install from source and run the server locally:

git clone https://github.com/yourusername/gmail-imap-mcp.git
cd gmail-imap-mcp

python -m venv .venv
# On Windows
.venv\Scripts\activate
# On Unix/MacOS
source .venv/bin/activate

pip install -e .

# Start the MCP server (HTTP API) on the default port
gmail-imap-mcp

# Optional: to run the server as a Python module directly
# python -m gmail_imap_mcp.server

Additional configuration and usage notes

Prepare your Google Cloud Project and OAuth credentials before authentication. Create a project, enable the Gmail API, and generate OAuth 2.0 client credentials. Place the downloaded client_secret.json file in your credentials directory.

Credential storage is in the user’s home directory at ~/.gmail_imap_mcp_credentials. This keeps sensitive tokens separate per user and persists across sessions.

Security and troubleshooting

Security: OAuth2 credentials are stored locally in ~/.gmail_imap_mcp_credentials. Do not share client_secret.json or token files. Ensure the credentials directory is writable in your environment.

Troubleshooting: If authentication fails, re-authenticate to refresh tokens. Verify Gmail API is enabled for your project and ensure the client_secret.json file is in the credentials directory. If you encounter connection issues, check your internet connection and any Google account security settings that might block IMAP access.

Email sending issues can arise from Gmail SMTP settings or attachment size limits. Confirm your account allows external SMTP use and that attachments do not exceed Gmail’s limits.

Starting and connecting the server with clients

To connect with clients that support MCP, start the server and point the client to the provided URL or local stdio channel. You can authenticate Gmail accounts with the built‑in authentication flow and then issue commands to read, search, send, and manage emails.

Notes on email IDs and labeling

Email identifiers follow the format email://message/{account}_{mailbox}_{id}. Use the full URI when moving emails between labels or marking them as read or unread. Gmail labels are managed through IMAP mailbox operations, and system labels like INBOX cannot be created or deleted.

Connecting with MCP clients (example workflows)

After authentication, you can ask your AI assistant to retrieve unread emails, search for messages by sender or subject, create labels, move messages to appropriate labels, download attachments, and draft or send new emails with optional CC/BCC and HTML content.

Usage prompts and supported actions

Supported actions include: authenticate-gmail, search-emails, get-unread-emails, send-email, create-label, delete-label, list-labels, move-email, download-attachment, mark-as-read, mark-as-unread, and summarize-emails.

Available tools

authenticate-gmail

Authorize a Gmail account for MCP access using OAuth2 and store credentials for future use.

search-emails

Query emails in a Gmail account with advanced criteria and return matching messages.

get-unread-emails

Retrieve unread emails from a specified mailbox.

send-email

Compose and send an email with optional CC/BCC, HTML content, and attachments.

create-label

Create a new Gmail label/mailbox within an account.

delete-label

Remove a Gmail label/mailbox from an account.

list-labels

List all labels/mailboxes for a Gmail account.

move-email

Move an email from one label/mailbox to another using the email URI.

download-attachment

Download an attachment from a specific email.

mark-as-read

Mark a specified email as read.

mark-as-unread

Mark a specified email as unread.

summarize-emails

Create a concise summary of recent emails from a mailbox.