Gmail IMAP MCP Server

A Model Context Protocol (MCP) server for Gmail integration using IMAP. This server allows AI assistants to interact with Gmail accounts, providing functionality to read, search, and manage emails.

Features

• OAuth2 authentication with Gmail
• Read emails from Gmail accounts
• Search emails with advanced query options
• View unread emails
• Send emails with attachments
• Manage labels (create, delete, list)
• Move emails between labels
• Download attachments
• Mark emails as read/unread
• Support for multiple Gmail accounts
• Integration with AI assistants through MCP

Prerequisites

Before running the Gmail IMAP MCP server, ensure you have the following:

1. Python 3.12 or higher
2. Google Cloud Project with Gmail API enabled
3. OAuth 2.0 Client ID credentials

Installation

Install from source

1. Clone the repository:

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

2. Create and activate a virtual environment:

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

3. Install the package:

   pip install -e .
   

Setup Google Cloud Project

1. Go to the Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Gmail API for your project:
   • Navigate to “APIs & Services” > “Library”
   • Search for “Gmail API” and enable it
4. Create OAuth 2.0 credentials:
   • Go to “APIs & Services” > “Credentials”
   • Click “Create Credentials” > “OAuth client ID”
   • Choose “Desktop app” as application type
   • Download the client configuration file
5. Save the downloaded file as client_secret.json in the credentials directory:

   mkdir -p ~/.gmail_imap_mcp_credentials
   # Move the downloaded file to ~/.gmail_imap_mcp_credentials/client_secret.json
   

Architecture and Implementation Details

Credential Storage

The Gmail IMAP MCP server stores OAuth2 credentials in the user’s home directory at ~/.gmail_imap_mcp_credentials/. This approach offers several advantages:

1. Security: Credentials are stored in a user-specific location rather than in the application directory
2. Persistence: Credentials persist across different sessions and application restarts
3. Compatibility: Avoids permission issues on read-only file systems

The credentials directory contains:

• client_secret.json: Your OAuth client credentials from Google Cloud Console
• Token files for each authenticated Gmail account (format: token_{email_address}.json)

IMAP Implementation

The server uses Python’s imaplib2 library for IMAP operations with Gmail. Key implementation details include:

1. Connection: Secure connection to Gmail’s IMAP server (imap.gmail.com) on port 993
2. Authentication: OAuth2 authentication using XOAUTH2 mechanism