Gmail IMAP MCP Server

What is Gmail IMAP MCP Server?

A Model Context Protocol (MCP) server for Gmail integration using IMAP. It enables AI assistants to read, search, and manage Gmail accounts through OAuth2 authentication and a set of IMAP-based tools.

How to use Gmail IMAP MCP Server?

Install from source with Python 3.12+, enable the Gmail API in a Google Cloud project, create OAuth2 credentials, and run the command gmail-imap-mcp. Use the authenticate-gmail tool to authenticate an account, then invoke tools like search-emails, send-email, or create-label.

Key features of Gmail IMAP MCP Server

• OAuth2 authentication with Gmail
• Read, search, and send emails with attachments
• Manage labels (create, delete, list)
• Move emails between labels
• Download attachments from emails
• Mark emails as read/unread
• Support for multiple Gmail accounts simultaneously

Use cases of Gmail IMAP MCP Server

• An AI assistant reads and summarizes recent inbox emails for a user.
• A user instructs an AI to search for emails from a specific sender and reply.
• An AI helps organize emails by creating labels and moving messages between them.
• A developer integrates Gmail management into a custom MCP-enabled AI workflow.

FAQ from Gmail IMAP MCP Server

How do I authenticate a Gmail account?

Use the authenticate-gmail tool with your email address. An OAuth2 flow will open in your browser; after granting permission, the server stores the token for future sessions.

What are the prerequisites?

Python 3.12 or higher, a Google Cloud Project with the Gmail API enabled, and OAuth 2.0 Client ID credentials (download as client_secret.json).

How do I start the server and connect it to Claude Desktop?

Run python -m gmail_imap_mcp.server to start the server. Then in Claude Desktop, navigate to Settings and configure the MCP server endpoint.

Where are credentials stored?

OAuth credentials and tokens are stored in ~/.gmail_imap_mcp_credentials/ — separate token files per account (format token_{email}.json). This location is user‑specific and persists across sessions.

What is the email ID format?

Email IDs follow the pattern email://message/{account}_{mailbox}_{id}, where account is the Gmail address, mailbox is the label, and id is the IMAP unique ID.