mcp-maildir

mcp-maildir is an MCP (Model Context Protocol) server allowing AI agents (Claude, OpenHands, Cursor, etc.) to explore, search, and read your email archives in a 100% offline, local, and strict Read-Only (R/O) manner.

This project uses an email dump in the Maildir format (e.g., generated via offlineimap), vectorizes the content locally for semantic search, and stores everything in Qdrant to provide ultra-fast hybrid search (Semantic + Exact filtering on metadata like dates or senders).

✨ Features

• 🔒 Strict Read-Only: The AI interacts with a Qdrant index; it has no direct access to your actual mailbox or the maildir files. Zero risk of accidental deletion or sending.
• 🧠 Hybrid Search:
  • Semantic: Find concepts ("farewell party organization") via local sentence-transformers.
  • Factual: Filter deterministically by sender or exact date ranges (thanks to Qdrant's native payload indexes).
• 🚀 MCP Standard: Instantly compatible with any client supporting the Model Context Protocol.

🏗️ Architecture

1. Source: Your local Maildir folder.
2. Indexer (indexer.py): A Python script that parses emails, extracts raw text, generates local embeddings, and pushes everything to Qdrant along with metadata.
3. Database: Qdrant (running locally via Docker).
4. MCP Server (server.py): Exposes search and read tools to the AI agent via FastMCP.

🛠️ Prerequisites

• Python 3.10+
• Docker (to run Qdrant)
• An email folder in Maildir format

🚀 Installation & Setup

1. Clone and prepare the environment

git clone https://github.com/your-username/mcp-maildir.git
cd mcp-maildir

# Create a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install mcp fastmcp qdrant-client sentence-transformers

2. Start Qdrant (Vector Database)

Run Qdrant locally in the background using Docker:

docker run -p 6333:6333 -p 6334:6334 \
    -v $(pwd)/qdrant_storage:/qdrant/storage:z \
    qdrant/qdrant

3. Configuration

Create a .env file or modify the variables in the code to point to your Maildir folder:

MAILDIR_PATH=/path/to/your/maildir/dump
QDRANT_URL=<http://localhost:6333>
COLLECTION_NAME=my_emails

4. Initial Indexing (Ingestion)

Before the AI can search, you need to index your emails. Run the ingestion script (to be executed every time you sync new emails):

python indexer.py

Note: The indexer.py script automatically configures Qdrant payload indexes for metadata (sender as KEYWORD, date as DATETIME) to guarantee fast and deterministic static searches.

🤖 Usage with an MCP Client

Tools exposed by the server

The server.py script exposes the following tools to the AI:

• search_emails(query: str, sender: str, start_date: str, end_date: str): Performs a hybrid search. Metadata parameters are optional.
• read_email(message_id: str): Returns the full text content (cleaned of HTML) of a specific email.