iMessage RAG MCP

Ein MCP-Server, der Ihren lokalen macOS-iMessage-Verlauf für KI-Assistenten durchsuchbar macht.

Er synchronisiert chat.db in eine lokale SQLite-Datenbank, teilt Konversationen in kontextbewusste Chunks auf und stellt hybride Suche (dense + lexical, fusioniert und neu gerankt) über einen MCP-Endpunkt bereit. Alles läuft lokal – keine Nachrichtendaten verlassen Ihren Rechner.

Funktionen

• Hybride Suche – FAISS-Dense-Vektorsuche fusioniert mit TF-IDF-lexikalischer Suche über reziproke Rangfusion, anschließend neu gerankt mit einem Cross-Encoder.

• Konversationsbewusstes Chunking – Nachrichten werden nach Zeitabständen in Sitzungen gruppiert und dann mit Überlappung gechunkt, sodass abgerufene Passagen kohärent bleiben.

• Kontexterweiterung – Ergebnisse enthalten umgebende Nachrichten, nicht nur den passenden Chunk.

• Kontaktnamensauflösung – Telefonnummern und E-Mails werden echten Namen aus Ihrem macOS-Adressbuch zugeordnet.

• Inkrementelle Synchronisierung – Ein Fingerabdruck der Quelldatenbank vermeidet redundante Arbeit, wenn sich nichts geändert hat.

• Nur lokal – Liest Apples Datenbanken schreibgeschützt; alle Indizes bleiben auf der Festplatte.

Related MCP server: iMessage Max

Anforderungen

• macOS (liest ~/Library/Messages/chat.db)

• Python 3.10+

• Vollzugriff auf die Festplatte für das Programm, das den Server ausführt (Terminal, iTerm, PyCharm usw.) – gewähren Sie ihn in Systemeinstellungen → Datenschutz & Sicherheit → Vollzugriff auf die Festplatte und starten Sie das Programm dann neu.

Installation

git clone git@github.com:jaredtkatz/imessage-rag-mcp.git
cd imessage-rag-mcp
python -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

Beim ersten Lauf werden die Embedding- und Reranker-Modelle von Hugging Face heruntergeladen (einige hundert MB).

Verwendung

Index erstellen und Server starten:

SYNC_ON_STARTUP=true ./run.sh

Die anfängliche Synchronisierung und der Indexaufbau können je nach Größe Ihres Nachrichtenverlaufs mehrere Minuten dauern. Bei späteren Läufen können Sie das Flag weglassen, um die Synchronisierung zu überspringen und sofort mit dem vorhandenen Index zu starten:

./run.sh

run.sh ist ein dünner Wrapper um:

python -m uvicorn mcp_server:app --host 0.0.0.0 --port 8000 --reload

Verbinden eines MCP-Clients

Weisen Sie Ihren MCP-Client auf:

http://localhost:8000/mcp

HTTP-Endpunkte

Beide Endpunkte sind auch direkt über HTTP nutzbar:

• GET /search?query=...&limit=8 – vollständige hybride Pipeline (dense + lexical → Fusion → Reranking → Kontexterweiterung). Dies ist das über MCP bereitgestellte Tool.

• GET /lexical?query=...&limit=20 – nur TF-IDF-Ergebnisse, nützlich zum Debuggen der Suche.

Konfiguration

Alle Einstellungen sind Umgebungsvariablen mit sinnvollen Standardwerten. Sie können in der Shell oder in einer .env-Datei im Projektstamm festgelegt werden:

cp .env.example .env

Shell-Variablen haben Vorrang vor .env, sodass Sie einen Dateiwert für einen einzelnen Lauf überschreiben können:

SYNC_ON_STARTUP=true ./run.sh

.env ist gitignored.

So funktioniert es

1. Erfassen (ingest.py) – liest neue und kürzlich geänderte Zeilen aus chat.db, stellt Text aus attributedBody wieder her, wenn die einfache text-Spalte leer ist, löst Absendernamen über das Adressbuch auf und fügt sie in die lokale kanonische Datenbank ein.

2. Indizieren (indexer.py) – gruppiert Nachrichten pro Chat, teilt sie bei Zeitabständen in Sitzungen auf, chunked jede Sitzung mit Überlappung und schreibt dann einen FAISS-Index und eine TF-IDF-Matrix.

3. Abrufen (rag.py) – führt Dense- und Lexical-Suche aus, fusioniert die Rankings mit RRF, rankt mit einem Cross-Encoder neu, verwirft überlappende Chunks und erweitert jedes Ergebnis um umgebende Nachrichten.

4. Bereitstellen (mcp_server.py) – stellt die Pipeline als FastAPI-App bereit, die als MCP-Server gemountet ist.

Projektstruktur

config.py       Environment-driven settings and file paths
db.py           SQLAlchemy models for chat.db, Address Book, and local storage
ingest.py       Sync from chat.db into the canonical database
indexer.py      Session splitting, chunking, and index construction
rag.py          Hybrid retrieval, fusion, reranking, context expansion
mcp_server.py   FastAPI application and MCP mount
run.sh          Development server launcher
.env.example    Template for local configuration

Datenspeicherung

Generierte Artefakte liegen in imessage_rag_data/ (gitignored):

messages.sqlite   Canonical messages and chunks
messages.faiss    Dense vector index
lexical.joblib    TF-IDF vectorizer and matrix
state.json        Sync watermark and source fingerprint

Löschen Sie das Verzeichnis, um einen sauberen Neuaufbau zu erzwingen.

Hinweise und Einschränkungen

• Die Synchronisierung erfolgt nur beim Start und nur, wenn SYNC_ON_STARTUP=true ist. Es gibt noch keine Hintergrund- oder On-Demand-Synchronisierung. Starten Sie den Server also neu, um neue Nachrichten zu übernehmen.

• Anhänge, Reaktionen und der Verlauf bearbeiteter Nachrichten werden nicht indiziert – nur Text.

• Die Ausführung von uvicorn mit mehreren Workern führt derzeit zu 404ern auf dem MCP-Mount, daher läuft der Server mit einem einzelnen Worker.

• Der gesamte Index wird bei jeder Änderung des Korpus von Grund auf neu aufgebaut; es gibt kein inkrementelles Reindizieren.