Uses Python as the runtime environment to implement the IMAP MCP server, providing email browsing, organization, and processing capabilities.
IMAP MCP Server
A Model Context Protocol (MCP) server that enables AI assistants to check email, process messages, and learn user preferences through interaction.
Overview
This project implements an MCP server that interfaces with IMAP email servers to provide the following capabilities:
Email browsing and searching
Email organization (moving, tagging, marking)
Email composition and replies
Interactive email processing and learning user preferences
Automated email summarization and categorization
Support for multiple IMAP providers
The IMAP MCP server is designed to work with Claude or any other MCP-compatible assistant, allowing them to act as intelligent email assistants that learn your preferences over time.
Features
Email Authentication: Secure access to IMAP servers with various authentication methods
Email Browsing: List folders and messages with filtering options
Email Content: Read message contents including text, HTML, and attachments
Email Actions: Move, delete, mark as read/unread, flag messages
Email Composition: Draft and save replies to messages with proper formatting
Support for plain text and HTML replies
Reply-all functionality with CC support
Proper threading with In-Reply-To and References headers
Save drafts to appropriate folders
Search: Basic search capabilities across folders
Interaction Patterns: Structured patterns for processing emails and learning preferences (planned)
Learning Layer: Record and analyze user decisions to predict future actions (planned)
Current Project Structure
The project is currently organized as follows:
Getting Started
Prerequisites
Python 3.8 or higher
An IMAP-enabled email account (Gmail recommended)
uv for package management and running Python scripts
Installation
Install uv if you haven't already:
curl -LsSf https://astral.sh/uv/install.sh | shClone and install the package:
git clone https://github.com/non-dirty/imap-mcp.git cd imap-mcp uv venv source .venv/bin/activate # On Windows: .venv\Scripts\activate uv pip install -e ".[dev]"
Gmail Configuration
Create a config file:
cp config.sample.yaml config.yamlSet up Gmail OAuth2 credentials:
Go to Google Cloud Console
Create a new project or select existing one
Enable the Gmail API
Create OAuth2 credentials (Desktop Application type)
Download the client configuration
Update
config.yaml
with your Gmail settings:imap: host: imap.gmail.com port: 993 username: your-email@gmail.com use_ssl: true oauth2: client_id: YOUR_CLIENT_ID client_secret: YOUR_CLIENT_SECRET refresh_token: YOUR_REFRESH_TOKEN
Usage
Checking Email
To list emails in your inbox:
Available options:
--folder
: Specify which folder to check (default: INBOX)--limit
: Maximum number of emails to display (default: 10)--verbose
: Enable detailed logging output
Starting the MCP Server
To start the IMAP MCP server:
For development mode with debugging:
Managing OAuth2 Tokens
To refresh your OAuth2 token:
To generate a new OAuth2 token:
Development
Setting Up Development Environment
Running Tests
Security Considerations
This MCP server requires access to your email account, which contains sensitive personal information. Please be aware of the following security considerations:
Store email credentials securely using environment variables or secure credential storage
Consider using app-specific passwords instead of your main account password
Limit folder access to only what's necessary for your use case
Review the permissions granted to the server in your email provider's settings
Project Roadmap
Project initialization and repository setup
Basic IMAP integration
Email resource implementation
Email tool implementation
Email reply and draft functionality
User preference learning implementation
Advanced search capabilities
Multi-account support
Integration with major email providers
Contributing
Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
License
This project is licensed under the MIT License - see the LICENSE file for details.
Acknowledgments
Model Context Protocol for providing the framework
Anthropic for developing Claude
Various Python IMAP libraries that make this project possible
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
A Model Context Protocol server that enables AI assistants to access and manage email through IMAP, supporting browsing, searching, reading, and organizing emails while learning user preferences over time.
Related MCP Servers
- -securityFlicense-qualityA versatile Model Context Protocol server that enables AI assistants to manage calendars, track tasks, handle emails, search the web, and control smart home devices.Last updated -19
- -securityFlicense-qualityA Model Context Protocol server that enables AI assistants to interact with Gmail services, supporting email operations, draft management, and calendar functionality through Google API integration.Last updated -3561
- -securityAlicense-qualityA Model Context Protocol server that enables AI assistants like Claude to interact with Gmail through natural language, providing comprehensive email management capabilities including sending, reading, organizing, searching, and managing drafts and labels.Last updated -7GPL 3.0
- -securityAlicense-qualityA Model Context Protocol server that enables AI assistants to manage Gmail through natural language interactions with features like sending emails, searching, and label management.Last updated -2,386MIT License