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:

.
├── examples/              # Example configurations
│   └── config.yaml.example
├── imap_mcp/              # Source code
│   ├── __init__.py
│   ├── config.py          # Configuration handling
│   ├── imap_client.py     # IMAP client implementation
│   ├── models.py          # Data models
│   ├── resources.py       # MCP resources implementation
│   ├── server.py          # Main server implementation
│   └── tools.py           # MCP tools implementation
├── tests/                 # Test suite
│   ├── __init__.py
│   └── test_models.py
├── INSTALLATION.md        # Detailed installation guide
├── pyproject.toml         # Project configuration
└── README.md              # This file

Getting Started

Prerequisites

• Python 3.8 or higher
• An IMAP-enabled email account (Gmail recommended)
• uv for package management and running Python scripts

Installation

1. Install uv if you haven't already:

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

2. Clone 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

1. Create a config file:

   cp config.sample.yaml config.yaml
   

2. Set 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

3. 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:

uv run list_inbox.py --config config.yaml --folder INBOX --limit 10

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 IMA

... View full README on GitHub