iMessage RAG MCP

Un servidor MCP que hace que tu historial local de iMessage en macOS sea buscable por asistentes de IA.

Sincroniza chat.db en una base de datos SQLite local, divide las conversaciones en fragmentos conscientes del contexto y sirve recuperación híbrida (densa + léxica, fusionada y reordenada) a través de un endpoint MCP. Todo se ejecuta localmente: ningún dato de mensajes sale de tu máquina.

Características

• Recuperación híbrida — búsqueda densa con FAISS fusionada con búsqueda léxica TF-IDF mediante fusión de rango recíproco, y luego reordenada con un cross-encoder.

• Fragmentación consciente de la conversación — los mensajes se agrupan en sesiones por intervalo de tiempo, luego se fragmentan con solapamiento para que los pasajes recuperados sean coherentes.

• Expansión de contexto — los resultados incluyen mensajes circundantes, no solo el fragmento coincidente.

• Resolución de nombres de contacto — los números de teléfono y correos electrónicos se asignan a nombres reales desde tu libreta de direcciones de macOS.

• Sincronización incremental — una huella digital de la base de datos fuente evita trabajo redundante cuando no ha cambiado nada.

• Solo local — lee las bases de datos de Apple en modo solo lectura; todos los índices permanecen en disco.

Related MCP server: iMessage Max

Requisitos

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

• Python 3.10+

• Acceso completo al disco para el programa que ejecute el servidor (Terminal, iTerm, PyCharm, etc.) — concédelo en Configuración del Sistema → Privacidad y Seguridad → Acceso completo al disco, y luego reinicia ese programa.

Instalación

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

La primera ejecución descarga los modelos de incrustación y reordenamiento de Hugging Face (unos cientos de MB).

Uso

Construye el índice e inicia el servidor:

SYNC_ON_STARTUP=true ./run.sh

La sincronización inicial y la construcción del índice pueden tardar varios minutos dependiendo del tamaño de tu historial de mensajes. En ejecuciones posteriores puedes omitir la bandera para omitir la sincronización e iniciar inmediatamente contra el índice existente:

./run.sh

run.sh es un envoltorio delgado alrededor de:

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

Conexión de un cliente MCP

Apunta tu cliente MCP a:

http://localhost:8000/mcp

Endpoints HTTP

Ambos endpoints también se pueden usar directamente a través de HTTP:

• GET /search?query=...&limit=8 — pipeline híbrido completo (denso + léxico → fusión → reordenamiento → expansión de contexto). Esta es la herramienta expuesta a través de MCP.

• GET /lexical?query=...&limit=20 — solo resultados TF-IDF, útil para depurar la recuperación.

Configuración

Todas las configuraciones son variables de entorno con valores predeterminados sensatos. Se pueden establecer en el shell o en un archivo .env en la raíz del proyecto:

cp .env.example .env

Las variables del shell tienen prioridad sobre .env, por lo que puedes anular un valor de archivo para una sola ejecución:

SYNC_ON_STARTUP=true ./run.sh

.env está en gitignore.

Cómo funciona

1. Ingesta (ingest.py) — lee filas nuevas y recientemente modificadas de chat.db, recupera texto de attributedBody cuando la columna text está vacía, resuelve nombres de remitentes contra la libreta de direcciones y actualiza la base de datos canónica local.

2. Índice (indexer.py) — agrupa mensajes por chat, los divide en sesiones por intervalos de tiempo, fragmenta cada sesión con solapamiento y luego escribe un índice FAISS y una matriz TF-IDF.

3. Recuperación (rag.py) — ejecuta búsqueda densa y léxica, fusiona los rankings con RRF, reordena con un cross-encoder, elimina fragmentos solapados y expande cada resultado con mensajes circundantes.

4. Servir (mcp_server.py) — expone el pipeline como una aplicación FastAPI montada como servidor MCP.

Estructura del proyecto

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

Almacenamiento de datos

Los artefactos generados viven en imessage_rag_data/ (en gitignore):

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

Elimina el directorio para forzar una reconstrucción limpia.

Notas y limitaciones

• La sincronización solo ocurre al inicio, y solo cuando SYNC_ON_STARTUP=true. Aún no hay sincronización en segundo plano o bajo demanda, así que reinicia el servidor para recoger nuevos mensajes.

• Los adjuntos, reacciones e historial de mensajes editados no se indexan — solo texto.

• Ejecutar uvicorn con múltiples workers actualmente causa errores 404 en el montaje MCP, por lo que el servidor se ejecuta con un solo worker.

• Todo el índice se reconstruye desde cero cada vez que el corpus cambia; no hay reindexación incremental.