Sagent
01d15c486e
The integration test job has been failing intermittently on main and on open pull requests with `httpx.ReadTimeout: timed out` on the first write to Qdrant, while `GET /collections` and `/healthz` kept answering. Cause: the qdrant-client default request timeout is 5 seconds, and the job only waits for `/healthz`, which is served before the storage engine accepts writes. On a shared runner doing several builds at once, the first collection creation or indexing exceeds 5s and the whole fixture errors out. - pin qdrant/qdrant to v1.19 (the digest `latest` and the cluster already run) and let Renovate track the pin in the workflows as well - wait for a real write round-trip (create + delete a probe collection) instead of `/healthz` alone, and dump the container logs if it never becomes writable - make the Qdrant client timeout configurable via QDRANT_TIMEOUT and set it to 60s in CI, where there is no latency SLA
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
maildirfiles. 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).
- Semantic: Find concepts ("farewell party organization") via local
- 🚀 MCP Standard: Instantly compatible with any client supporting the Model Context Protocol.
🏗️ Architecture
- Source: Your local
Maildirfolder. - Indexer (
indexer.py): A Python script that parses emails, extracts raw text, generates local embeddings, and pushes everything to Qdrant along with metadata. - Database: Qdrant (running locally via Docker).
- MCP Server (
server.py): Exposes search and read tools to the AI agent viaFastMCP.
🛠️ Prerequisites
- Python 3.10+
- Docker (to run Qdrant)
- An email folder in
Maildirformat
🚀 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.