# 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

```bash
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:

```sh
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):

```sh
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.