82 lines
3.0 KiB
Markdown
82 lines
3.0 KiB
Markdown
# 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.
|