Multimodales iMessage MCP

Der vollständigste iMessage MCP-Server für Claude. Lies vollständige Unterhaltungen, durchsuche Nachrichten, betrachte Bildanhänge, sende Nachrichten, suche Kontakte und reagiere auf Nachrichten – alles von Claude Desktop oder Claude Code aus.

Warum dieses Tool existiert

Jedes andere iMessage MCP-Tool fragt die Spalte text in Apples chat.db ab. Das Problem? Auf modernem macOS (14+) sind 93 % der Nachrichten in attributedBody statt in text gespeichert. Diese Tools geben stillschweigend leere oder unvollständige Unterhaltungen zurück.

Dieser Server hat Apples binäres NSAttributedString-Format rückentwickelt, um den tatsächlichen Nachrichteninhalt zu extrahieren und dir Zugriff auf deine vollständige Nachrichtenhistorie zu geben.

Related MCP server: jons-mcp-imessage

Funktionen

Multimodal: Claude kann deine Fotos sehen

Wenn du get_attachment verwendest, werden Bilder als base64-Inhaltsblöcke zurückgegeben, die Claude tatsächlich ansehen kann. HEIC-Fotos (iPhone-Standard) werden automatisch in JPEG konvertiert. Das bedeutet, Claude kann:

• Beschreiben, was auf einem Foto ist, das dir jemand geschickt hat

• Text/Screenshots aus Bildern lesen

• Visuelle Inhalte in deinen Unterhaltungen analysieren

Voraussetzungen

• macOS (dieses liest die lokale iMessage-Datenbank)

• Node.js >= 18 und < 26. Node 24 LTS wird empfohlen, da die gesperrte native SQLite-Abhängigkeit nicht mit Node 26 kompatibel ist.

• Voller Festplattenzugriff für deine Terminal-App (Systemeinstellungen > Datenschutz & Sicherheit > Voller Festplattenzugriff). Dies deckt sowohl die iMessage-Datenbank als auch die für die Kontaktnamensauflösung verwendete Adressbuch-Datenbank ab – die Kontakte-App muss nicht geöffnet sein.

Installation

git clone https://github.com/tszaks/imessage-mcp.git
cd imessage-mcp
npm install

Konfiguration

Claude Desktop

Füge zu deiner ~/Library/Application Support/Claude/claude_desktop_config.json hinzu:

{
  "mcpServers": {
    "imessage": {
      "command": "/opt/homebrew/bin/node",
      "args": ["/path/to/imessage-mcp/index.js"]
    }
  }
}

Wichtig: Verwende den vollständigen Pfad zu deiner Node.js-Binärdatei (z. B. /opt/homebrew/bin/node), nicht nur node. macOS-Desktop-Apps übernehmen nicht die PATH-Variable deiner Shell, und die Verwendung eines bloßen node-Befehls führt oft zu einer älteren System-Node, die native Modulabstürze verursacht.

Claude Code

Füge zu deiner .mcp.json hinzu:

{
  "mcpServers": {
    "imessage": {
      "command": "node",
      "args": ["/path/to/imessage-mcp/index.js"]
    }
  }
}

In Claude Code wird node typischerweise korrekt aufgelöst, da es die Shell-Umgebung übernimmt.

Verwendungsbeispiele

"Zeig mir meine neuesten Nachrichten" – liest deine letzten Unterhaltungen

"Was hat Mama mir heute geschrieben?" – löst "Mama" über dein Adressbuch in eine Telefonnummer auf und ruft die Unterhaltung ab

"Durchsuche meine Nachrichten nach 'Flugbestätigung'" – Volltextsuche über alle Nachrichten

"Finde Outreach-Kandidaten aus den letzten 7 Tagen, die geantwortet haben und eine Nachverfolgung benötigen" – gibt strukturierte Outreach-Kandidaten mit Risikobewertungen zurück

"Zeige eine Vorschau dieses Batches von 10 Folgetexten" – gibt genaue Empfänger, Nachrichten, Warnungen und einen Freigabe-Token zurück, bevor etwas gesendet wird

"Zeige kürzliche Sendefehler" – meldet ausgehende Nachrichten, die von Nachrichten als fehlgeschlagen oder ausstehend markiert wurden, einschließlich ob eine spätere SMS/RCS-Sendung den Thread wiederhergestellt hat

"Zeig mir das Foto von Nachricht 538516" – gibt das tatsächliche Bild zurück, damit Claude es ansehen und beschreiben kann

"Sende 'Komme 10 Min zu spät' an +1234567890" – sendet eine iMessage (erfordert Bestätigung)

Release-Flags

Release-Flags sind opt-in über die MCP-Server-Umgebung:

{
  "mcpServers": {
    "imessage": {
      "command": "node",
      "args": ["/path/to/imessage-mcp/index.js"],
      "env": {
        "IMESSAGE_MCP_RELEASES": "auto_sms_fallback,cleanup_failed_imessage_after_sms_fallback,message_mutation_tools,experimental_message_ui_actions,read_receipts"
      }
    }
  }
}

Mutationstools

delete_messages akzeptiert genaue Nachrichten-ROWIDs:

{ "message_ids": ["538516", "538517"] }

Es erfordert keine Bestätigung. Es meldet gelöschte IDs, fehlende IDs, Backup-Speicherort und alle verbleibenden Zeilen, die während der Überprüfung gefunden wurden.

delete_threads ist ein zweistufiger genauer Batch-Ablauf:

{ "chat_ids": [101, 102] }

Die Vorschau gibt einen approval_token für diese geordnete Liste und die in der Vorschau angezeigten Thread-Metadaten zurück. Zum Löschen sende die gleiche geordnete chat_ids, confirm: true und diesen Token:

{ "chat_ids": [101, 102], "confirm": true, "approval_token": "..." }

Eine Änderung der Reihenfolge, der Liste oder des Tokens führt zum Fehlschlagen der Anfrage.

edit_message und undo_send_message sind experimentell, da Nachrichten keine erstklassigen AppleScript-Befehle für diese Aktionen bereitstellt. Sie öffnen die Unterhaltung, finden die sichtbare ausgehende Blase anhand eines Textausschnitts, verwenden das Kontextmenü und überprüfen dann das Ergebnis. Sie sollen das tatsächliche Nachrichten-Verhalten beeinflussen, keine gefälschten lokalen DB-Bearbeitungen.

Optionale Anpassung:

IMESSAGE_MCP_SEND_VERIFY_DELAY_MS=2500

Dies steuert, wie lange der MCP wartet, bevor er die lokale Nachrichten-Datenbank auf die neue ausgehende Zeile überprüft.

Wie es funktioniert

Die attributedBody-Korrektur

Apples iMessage-Datenbank (~/Library/Messages/chat.db) hat zwei Spalten für Nachrichteninhalte:

• text – die alte Klartext-Spalte (von älteren macOS-Versionen verwendet)

• attributedBody – ein serialisierter NSAttributedString-Blob (von macOS 14+ verwendet)

Auf modernem macOS hat Apple nach und nach die Nachrichtenspeicherung auf attributedBody umgestellt, um Rich Text, Erwähnungen und Formatierung zu unterstützen. Die Spalte text ist zunehmend nur ein Legacy-Fallback, der oft NULL ist.

Dieser Server erkennt Nachrichten mit NULL-text und extrahiert den Inhalt aus attributedBody, indem er das binäre NSTypedStream-Format parst:

1. Findet den NSString-Marker im binären Blob

2. Liest über die Typ-Header-Bytes (01 94 84 01 2b) hinweg

3. Dekodiert das Längenpräfix (ein Byte für kurze Nachrichten, mehrere Bytes für längere)

4. Extrahiert die UTF-8-Textnutzlast

Anhangbehandlung

iMessage-Anhänge werden in ~/Library/Messages/Attachments/ gespeichert, wobei die Pfade in der Tabelle attachment verfolgt werden. Das Tool get_attachment:

1. Fragt die Anhangsmetadaten für eine bestimmte Nachrichten-ID ab

2. Löst den Pfad ~/Library/Messages/... in einen absoluten Pfad auf

3. Für JPEG/PNG/GIF/WebP: liest die Datei und gibt base64-Bildinhalt zurück

4. Für HEIC (iPhone-Standard): konvertiert mit macOS sips in JPEG vor der Rückgabe

5. Für andere Dateien: gibt Metadaten und den Dateipfad zurück

Fehlerbehebung

"Fehler beim Öffnen der iMessage-Datenbank" Gewähre deiner Terminal-App vollen Festplattenzugriff: Systemeinstellungen > Datenschutz & Sicherheit > Voller Festplattenzugriff.

Kontaktsuche liefert keine Ergebnisse Die Kontaktauflösung liest direkt die macOS-Adressbuch-SQLite-Datenbanken (keine Kontakte-App erforderlich). Stelle sicher, dass voller Festplattenzugriff gewährt wurde. Wenn ein Kontakt gerade erst hinzugefügt wurde, starte den MCP-Server neu, um den Cache zu aktualisieren.

Nativer Modulabsturz / "NODE_MODULE_VERSION mismatch" Baue native Abhängigkeiten neu: npm rebuild. Dies passiert, wenn sich deine Node.js-Version ändert. Stelle außerdem sicher, dass deine Claude Desktop-Konfiguration den vollständigen Pfad zu node verwendet (siehe Konfiguration oben).

Fehlende Nachrichten aus einer Unterhaltung Dies ist genau der Fehler, den dieser Server behebt. Stelle sicher, dass du die neueste Version ausführst, die die attributedBody-Extraktion enthält.

Lizenz

MIT

Kurzanleitung TL;DR

npm install
node index.js

Fügen Sie dann den Server zu Ihrer MCP-Client-Konfiguration hinzu und gewähren Sie Ihrer Terminal-App Full Disk Access.

So funktioniert es (TL;DR)

• Liest die macOS iMessage SQLite-Datenbank aus

• Dekodiert moderne attributedBody-Payloads für vollständigen Nachrichtentext

• Stellt Konversations-/Such-/Anhang-Tools über MCP bereit

• Verwendet AppleScript für Nachrichten-Sende-/Reaktions-Aktionen mit expliziten Bestätigungen

LLM-Schnellkopie

Verwenden Sie die Kopier-Schaltfläche auf diesem Codeblock in GitHub.

Repo: imessage-mcp
Goal: Full iMessage MCP including attachments and send/reaction actions.
Setup:
1) npm install
2) Grant Full Disk Access to terminal app
3) Add MCP config entry for index.js
Use:
- read_recent_messages, search_messages, get_conversation
- list_chats_structured, get_conversation_by_chat_id, find_outreach_followups
- get_attachment for image/file analysis
- send_message/send_message_batch/react_to_message with explicit confirm flag
How it works:
- SQLite + attributedBody decoding + AppleScript actions wrapped as MCP tools