iMessage RAG MCP

一个 MCP 服务器，让 AI 助手可以搜索你本地 macOS 的 iMessage 历史记录。

它将 chat.db 同步到本地 SQLite 数据库，将对话拆分为上下文感知的块，并通过 MCP 端点提供混合检索（稠密 + 词法，融合并重排序）。一切都在本地运行——没有消息数据离开你的机器。

特性

• 混合检索 — FAISS 稠密向量搜索与 TF-IDF 词法搜索通过倒数排名融合（RRF）融合，然后使用交叉编码器重排序。

• 对话感知分块 — 消息按时间间隔分组为会话，然后带重叠进行分块，使检索到的段落保持连贯。

• 上下文扩展 — 结果包含周围的消息，而不仅仅是匹配的块。

• 联系人姓名解析 — 电话号码和电子邮件从你的 macOS 通讯录映射到真实姓名。

• 增量同步 — 源数据库的指纹可避免在无变化时进行冗余工作。

• 仅本地 — 只读方式读取 Apple 的数据库；所有索引都保留在磁盘上。

Related MCP server: iMessage Max

要求

• macOS（读取 ~/Library/Messages/chat.db）

• Python 3.10+

• 运行服务器的程序（终端、iTerm、PyCharm 等）需要完全磁盘访问权限——在系统设置 → 隐私与安全性 → 完全磁盘访问权限中授予，然后重新启动该程序。

安装

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

首次运行会从 Hugging Face 下载嵌入和重排序模型（几百 MB）。

用法

构建索引并启动服务器：

SYNC_ON_STARTUP=true ./run.sh

初始同步和索引构建可能需要几分钟，具体取决于消息历史的大小。在后续运行中，你可以省略该标志以跳过同步并立即针对现有索引启动：

./run.sh

run.sh 是以下命令的薄包装：

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

连接 MCP 客户端

将你的 MCP 客户端指向：

http://localhost:8000/mcp

HTTP 端点

两个端点也可以直接通过 HTTP 使用：

• GET /search?query=...&limit=8 — 完整混合管道（稠密 + 词法 → 融合 → 重排序 → 上下文扩展）。这是通过 MCP 暴露的工具。

• GET /lexical?query=...&limit=20 — 仅 TF-IDF 结果，用于调试检索。

配置

所有设置都是具有合理默认值的环境变量。它们可以在 shell 中或项目根目录的 .env 文件中设置：

cp .env.example .env

Shell 变量优先于 .env，因此你可以为单次运行覆盖文件值：

SYNC_ON_STARTUP=true ./run.sh

.env 已被 gitignore。

工作原理

1. 摄取（ingest.py）— 从 chat.db 读取新增和最近更改的行，当纯 text 列为空时从 attributedBody 恢复文本，根据通讯录解析发送者姓名，并 upsert 到本地规范数据库。

2. 索引（indexer.py）— 按聊天分组消息，按时间间隔拆分为会话，带重叠对每个会话进行分块，然后写入 FAISS 索引和 TF-IDF 矩阵。

3. 检索（rag.py）— 运行稠密和词法搜索，使用 RRF 融合排名，使用交叉编码器重排序，丢弃重叠块，并用周围消息扩展每个结果。

4. 服务（mcp_server.py）— 将管道作为 FastAPI 应用挂载为 MCP 服务器。

项目布局

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

数据存储

生成的工件位于 imessage_rag_data/（已 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

删除该目录以强制干净重建。

注意事项和限制

• 同步仅在启动时进行，且仅当 SYNC_ON_STARTUP=true 时。目前没有后台或按需同步，因此重启服务器以获取新消息。

• 附件、反应和编辑消息历史不会被索引——仅文本。

• 使用多个 worker 运行 uvicorn 目前会导致 MCP 挂载出现 404，因此服务器以单 worker 运行。

• 每当语料库发生变化时，整个索引都会从头重建；没有增量重新索引。