Gmail IMAP MCP Server
@tonykipkemboi
Gmail IMAP MCP server for integrating Gmail with Claude and other AI assistants
Overview
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.
