imessage-rich-search

Volltextsuche in macOS iMessages — einschließlich der Metadaten von Link-Vorschauen (Titel, Zusammenfassungen, Seitennamen), die von der Messages.app indiziert werden, aber in der rohen chat.db-Textspalte niemals sichtbar sind.

Das Problem, das dies löst

Wenn Sie eine URL in iMessage einfügen, ruft macOS eine Rich-Vorschau ab — Titel, Zusammenfassung, Seitenname, Hero-Bild — und speichert diese Metadaten in der chat.db als NSKeyedArchiver-Blob in message.payload_data. Die Suchleiste der Messages.app liest dies aus. Die grundlegende text-Spalte der chat.db enthält diese Informationen nicht.

Wenn Ihnen also ein Freund https://x.com/foo/status/123 gesendet hat und die Vorschaukarte lautete "Obsidian + Claude Code is the most underrated productivity stack" — dann liefert die Suche nach "obsidian" in jedem Tool, das nur den text liest, null Ergebnisse. Die Messages.app findet es. Dieses Tool findet es. Beide durchsuchen denselben Datenbestand.

Related MCP server: imessage-mcp

Funktionen

• Durchsucht den Nachrichtentext und die dekodierten Metadaten der Link-Vorschau in einem Durchgang

• Filtern nach Kontakt (Telefonnummer / E-Mail)

• Menschenlesbare oder JSON-Ausgabe

• Schreibgeschützter Zugriff auf chat.db (verwendet den SQLite-URI-Modus)

• Keine Laufzeitabhängigkeiten für das CLI (nur Python-Standardbibliothek)

• Optionaler MCP-Server, damit Claude Desktop / Claude.ai ihn direkt aufrufen kann

• Ergebnisse sortiert nach Aktualität, ISO 8601-Zeitstempel, Richtungspfeile, rowid für Querverweise

Was es ist — und was nicht

Es ist:

• Eine schreibgeschützte forensische / Archiv-Suche über Ihre lokale chat.db

• Eine direkte Ergänzung zu MCP-iMessage-Tools, die nur reinen Text sehen

• ~200 Zeilen Standard-Python

Es ist nicht:

• Ein Ersatz für die Messages.app (keine Benutzeroberfläche, kein Senden/Bearbeiten/Löschen)

• Eine Möglichkeit, auf die Nachrichten anderer Personen zuzugreifen

• Ein iCloud / geräteübergreifendes Synchronisierungstool — durchsucht nur, was lokal auf diesem Mac vorhanden ist

• Eine Umgehung für den Vollzugriff auf die Festplatte — Sie müssen diesen explizit gewähren

• Ein OCR- / Bild- / Audio- / Sticker- / Handschrifterkennungs-Tool (nur Text + Link-Metadaten)

• Eine Möglichkeit, gelöschte Nachrichten wiederherzustellen, die nicht mehr in SQLite vorhanden sind

Anforderungen

Die chat.db-Schemafelder, auf die es sich stützt (text, payload_data, balloon_bundle_id, handle.id), sind seit macOS 10.13 High Sierra stabil; dieses Tool wird wahrscheinlich auch auf älteren Versionen funktionieren, wurde dort jedoch nicht getestet.

Installation

Option A — pipx (empfohlen, System-Python für MCP-Server erforderlich)

pipx isoliert das Tool in seiner eigenen venv. Installieren Sie bei Bedarf zuerst pipx:

brew install pipx
pipx ensurepath

Installieren Sie dann dieses Tool von GitHub. Verwenden Sie explizit /usr/bin/python3 — dies ist wichtig für den MCP-Server, da macOS den Vollzugriff auf die Festplatte nur von der Claude.app an von Apple signierte Kindprozesse weitergibt. Homebrew-Python ist von Drittanbietern signiert; das System-/usr/bin/python3 ist von Apple signiert und erbt die Berechtigungen sauber. Wenn Sie den MCP-Server nicht benötigen (nur CLI), funktioniert jedes Python 3.9+.

pipx install --python /usr/bin/python3 "git+https://github.com/cannavis/imessage-rich-search"

Dies installiert drei Befehle in Ihrem PATH (unter ~/.local/bin):

• imessage-rich-search — das CLI

• imrs — ein kurzer Alias für das CLI

• imessage-rich-search-mcp — der MCP-Server

Option B — pip in eine venv

git clone https://github.com/cannavis/imessage-rich-search
cd imessage-rich-search
/usr/bin/python3 -m venv .venv && source .venv/bin/activate
pip install -e .

Option C — Einzeldatei, keine Installation

Das CLI-Modul hat keine Abhängigkeiten. Sie können es per curl herunterladen und ausführen:

curl -O https://raw.githubusercontent.com/cannavis/imessage-rich-search/main/src/imessage_rich_search/cli.py
python3 cli.py "obsidian"

Vollzugriff auf die Festplatte gewähren (einmalig, erforderlich)

chat.db ist durch macOS TCC gesperrt. Ohne Vollzugriff erhalten Sie unable to open database file.

1. Öffnen Sie Systemeinstellungen → Datenschutz & Sicherheit → Vollzugriff auf die Festplatte

2. Klicken Sie auf + und fügen Sie die App hinzu, von der aus Sie dies ausführen:

   • Führen Sie imessage-rich-search direkt in der Shell aus? → fügen Sie Terminal (oder iTerm, Warp, Ghostty, Alacritty usw. — je nachdem, welches Terminal Sie tatsächlich verwenden) hinzu

   • Führen Sie es von Claude Desktop über MCP aus? → fügen Sie Claude.app hinzu

   • Führen Sie es von einem Skript-Editor oder einer IDE aus? → fügen Sie diese App hinzu

3. Beenden Sie die App vollständig und starten Sie sie neu (⌘Q, nicht nur das Fenster schließen), damit die Berechtigung wirksam wird

4. Überprüfung: python3 -c "import sqlite3; sqlite3.connect('file:'+__import__('os').path.expanduser('~/Library/Messages/chat.db')+'?mode=ro', uri=True).execute('SELECT COUNT(*) FROM message').fetchone()" — sollte eine Zahl ausgeben und keinen Fehler werfen

Verwendung

# Basic search across all conversations
imessage-rich-search "obsidian"

# Restrict to one contact
imessage-rich-search "obsidian" --contact "+14073993471"

# JSON for piping into jq, scripts, or another tool
imessage-rich-search "obsidian" --contact "+14073993471" --json | jq '.[].preview[0]'

# Limit results, point at a backup chat.db
imessage-rich-search "claude code" --limit 20 --db /path/to/chat.db

# Short alias
imrs "obsidian"

# Module form (no entry point needed)
python3 -m imessage_rich_search "obsidian"

Ausgabe

6 match(es) for 'obsidian':

[2026-04-08T22:56:23+00:00] -> +14073993471  (rowid=234953)
    url:     https://x.com/aiedge_/status/2041908011078447222?s=42
  * preview: Claude Code + Obsidian Ultimate Guide (build an AI second brain)
...

-> = gesendet · <- = empfangen · * = Vorschauzeile, die Ihre Suchanfrage enthält · rowid = Querverweis-Schlüssel in die chat.db.

Verwendung als MCP-Server (Claude Desktop)

Ermöglicht es Claude Desktop, die Suche während Unterhaltungen direkt aufzurufen.

1. Installieren Sie das Paket mit System-Python (Option A oben mit --python /usr/bin/python3). Dies ist erforderlich: Der macOS-Vollzugriff auf die Festplatte wird nur von der Claude.app an von Apple signierte Unterprozesse weitergegeben. /usr/bin/python3 ist von Apple signiert; Homebrew- / pyenv- / asdf-installierte Pythons sind dies nicht und werden von tccd stillschweigend abgelehnt.

2. Suchen Sie den absoluten Pfad des Einstiegspunkts: which imessage-rich-search-mcp

3. Bearbeiten Sie ~/Library/Application Support/Claude/claude_desktop_config.json:

   {
     "mcpServers": {
       "imessage-rich-search": {
         "command": "/full/path/from/which/imessage-rich-search-mcp"
       }
     }
   }

4. Bestätigen Sie, dass Claude.app bereits Vollzugriff auf die Festplatte hat (dies ist standardmäßig der Fall, sobald Sie ihn einmal gewährt haben — überprüfen Sie dies unter Systemeinstellungen → Datenschutz & Sicherheit → Vollzugriff auf die Festplatte)

5. Beenden Sie Claude Desktop vollständig und starten Sie es neu (⌘Q)

Claude kann nun search_imessages_rich(query, contact?, limit?) als Tool aufrufen.

Überprüfung, ob die TCC-Vererbung funktioniert

Wenn der MCP-Server innerhalb von Claude Desktop "unable to open database file" zurückgibt, ist die Kette der Prozess-Zuweisung unterbrochen. Überprüfen Sie das TCC-Daemon-Protokoll von macOS:

log show --predicate 'process == "tccd"' --last 5m | grep -iE "imessage-rich|chat\.db|SystemPolicyAllFiles"

Eine funktionierende Installation zeigt, dass die Anfrage zugelassen wurde. Eine fehlerhafte Installation zeigt responsible_path=, das auf ein nicht von Apple signiertes Python-Binärprogramm verweist, gefolgt von recording denied. Installieren Sie es mit pipx install --python /usr/bin/python3 ... neu, um das Problem zu beheben.

Funktionsweise

chat.db (SQLite, read-only)
  └─ message
       ├─ text                     ← raw text (what basic tools see)
       ├─ payload_data  (BLOB)     ← NSKeyedArchiver bplist of LPLinkMetadata
       │                              (title, summary, site, image refs)
       └─ balloon_bundle_id        ← e.g. com.apple.messages.URLBalloonProvider

For every row:
  1. Read text + payload_data
  2. plistlib.loads(payload_data) → walk $objects → collect strings
  3. Lower-case haystack = text + "\n".join(preview_strings)
  4. Match if query.lower() in haystack

Der Trick, "Strings aus $objects zu extrahieren", vermeidet die Notwendigkeit von ccl_bplist, pyobjc oder vollständiger NSKeyedUnarchiver-Semantik — für die Volltextsuche interessieren uns nicht die Objektgraphen, sondern nur die Blatt-Strings.

Datenschutz & Sicherheit

• Schreibgeschützt. Öffnet chat.db mit dem SQLite-URI-Flag mode=ro.

• Nur lokal. Keine Netzwerkaufrufe. Niemals. (grep -r 'urllib\|requests\|http' src/ gibt nichts zurück.)

• Keine Telemetrie.

• Keine Daten verlassen Ihren Mac, es sei denn, Sie entscheiden sich, die Ausgabe zu teilen.

• Das CLI hat null Laufzeitabhängigkeiten — es gibt nichts, das über die Lieferkette angegriffen werden könnte.

• Siehe SECURITY.md für die Meldung von Sicherheitslücken.

Einschränkungen

• Nur Teilübereinstimmungen. Kein FTS5-Ranking, kein Regex, keine booleschen Operatoren. Fügen Sie es hinzu, wenn Sie es möchten (PR welcome).

• Nur lokale Datenbank. Wenn eine Nachricht nur in iCloud lebt und nicht mit der chat.db dieses Macs synchronisiert wurde, wird sie nicht angezeigt.

• Vorschau-Metadaten hängen davon ab, ob Messages.app sie abgerufen hat. Wenn die Link-Karte nie geladen wurde (Offline-Versand, abgelaufene URL), gibt es keine payload_data zum Durchsuchen.

• String-Extraktion ist konzeptbedingt verlustbehaftet. Sie zieht jeden String aus der bplist; gelegentlich sehen Sie Bild-MIME-Typen, Dimensionstupel wie {0, 0} oder Profilbild-URLs in der Vorschau-Liste. Sie beeinflussen die Suchergebnisse nicht, erscheinen aber in der Rohausgabe.

• Vollzugriff auf die Festplatte ist eine harte Anforderung — es gibt keinen Workaround.

Fehlerbehebung

Mitwirken

Siehe CONTRIBUTING.md. Issues und PRs sind willkommen.

Changelog

Siehe CHANGELOG.md.

Lizenz

MIT — siehe LICENSE.

Danksagungen

• Apples chat.db-Schema, das über ein Jahrzehnt an macOS-Veröffentlichungen hinweg bemerkenswert stabil geblieben ist

• Die Leute, die im Laufe der Jahre payload_data / LPLinkMetadata durch Reverse Engineering entschlüsselt haben

• Model Context Protocol für die MCP-Spezifikation