lane-mac-mcp

Ein schreibgeschützter iMessage-MCP-Server + CLI für macOS. Eine auditierbare Datei, keine Sende-Fähigkeit.

Claude (über MCP) oder Sie selbst (über die CLI) können Unterhaltungen auflisten, einen Chat lesen und den Nachrichtenverlauf durchsuchen – und sonst nichts. Konstruktionsbedingt schreibgeschützt: v1 enthält überhaupt keinen Sende-Code. Alle Datenzugriffe laufen über Apples eigenes /usr/bin/sqlite3 mit -json -readonly gegen ~/Library/Messages/chat.db; Kontaktnamen stammen aus Read-only-Abfragen an die lokalen AddressBook-Datenbanken.

Design-Einschränkungen

Der gesamte Server ist server.ts (~600 Zeilen, Kommentare enthalten), damit er Ende-zu-Ende geprüft werden kann – die auditierte Datei ist die laufende Datei, da Node ≥ 22.18 TypeScript direkt mit nativem Type-Stripping ausführt (kein Build-Schritt, keine kompilierten Artefakte). Es gibt genau zwei Abhängigkeiten, fixiert über package-lock.json: @modelcontextprotocol/sdk und zod. Keine Netzwerk-Imports, keine offenen Ports – nur stdio-JSON-RPC, das von Claude Desktop als Kindprozess gestartet wird; CLI-Aufrufe sind Einmalprozesse. Es gibt keinen Daemon: Claude Desktop startet und beendet den Server zusammen mit der App (starten Sie die App neu, um Code zu laden).

Related MCP server: imessage-rich-search

Voraussetzungen

macOS mit eingerichteten Messages, Node.js ≥ 22.18 und Full Disk Access für den Prozess, der den Server ausführt: Terminal (oder Ihre Terminal-App) für die CLI-Nutzung und Claude Desktop für die MCP-Nutzung. Gewähren Sie ihn unter System Settings → Privacy & Security → Full Disk Access und starten Sie die App danach neu. node server.ts doctor prüft all dies und zeigt die fehlenden Punkte.

Setup

git clone <this repo> && cd MacMCPServer
npm install          # installs the two pinned dependencies
node server.ts doctor

Fügen Sie den Server dann zur claude_desktop_config.json von Claude Desktop hinzu (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "lane-mac": {
      "command": "node",
      "args": ["/Users/you/Desktop/MacMCPServer/server.ts"]
    }
  }
}

Starten Sie Claude Desktop neu. Daraufhin erscheinen drei Tools: list_chats, read_chat, search_messages.

CLI-Nutzung

node server.ts chats                                   # recent chats, names resolved
node server.ts chats --search "mom" --limit 5
node server.ts chats --awaiting-reply-only             # threads where the last word wasn't yours
node server.ts read "Martha" --limit 100               # fuzzy name; ambiguous → candidates
node server.ts read 42 --start-date 2024-01-01 --end-date 2024-06-30 --include-reactions
node server.ts search "dinner" --from "martha"         # last 30 days by default
node server.ts search "dinner" --start-date 2015-01-01 --deep   # older history + rich-text decode
node server.ts doctor

Die Ausgabe ist JSON. search deckt message.text per SQL LIKE ab; --deep dekodiert zusätzlich Nachrichten, deren Text nur im Blob attributedBody steckt (begrenzter Scan, langsamer). Tapback-Reaktionen werden überall ausgeschlossen, außer mit --include-reactions.

Behandelte Apple-Eigenheiten

Zeitstempel sind Nanosekunden seit dem 01.01.2001 (bei sehr alten Zeilen Sekunden) – beide Formate werden umgerechnet. Nachrichtentext liegt häufig im Typedstream-Blob attributedBody statt in message.text; er wird in JS mit der bekannten NSString-Heuristik dekodiert. Kontaktnamen werden über normalisierte Telefonnummern (letzte zehn Ziffern) oder kleingeschriebene E-Mail-Adressen über alle AddressBook-Quellen abgeglichen; bei unlesbaren Kontakten erfolgt ein sauberer Rückfall auf die rohen Nummern.

Datenschutz- & Sicherheitskonzept

Der Server kann immer nur lesen. Er öffnet die Datenbanken mit dem -readonly-Flag von sqlite3 und enthält keinen Codepfad, der eine Datenbank beschreibt, eine Nachricht sendet, eine Netzwerkverbindung herstellt oder einen Port öffnet. Benutzereingaben werden in SQL-Stringliterale escaped (''-Verdoppelung), und numerische Werte werden validiert. doctor gibt ausschließlich Zeilenzahlen aus, niemals Nachrichteninhalte. Umgebungsüberschreibungen (CHAT_DB_PATH, SQLITE_BIN, ADDRESSBOOK_DIR) existieren, damit Tests nie echte Daten anfassen.

Tests

npm test

Black-Box-Tests erzeugen eine synthetische chat.db-Datenbank und ein AddressBook-Fixture (einschließlich einer ausschließlich im attributedBody vorliegenden Nachricht, einem Tapback und einem unbeantworteten eingehenden Thread) und steuern die echte CLI sowie die echte MCP-stdio-Schnittstelle als Kindprozesse. Entwicklung arbeitet nie mit echten Daten.

Roadmap (später, nicht v1)

Kontaktanreicherung polieren → Notizen mit osascript lesen → Senden hinter einer SEND_ENABLED-Umgebungsvariable plus Genehmigung pro Aufruf.