iMessage MCP

Ein Deno-Monorepo mit Paketen für den iMessage-Zugriff unter macOS:

• @wyattjoh/imessage – Kernbibliothek für den schreibgeschützten Zugriff auf die iMessage-Datenbank

• @wyattjoh/imessage-mcp – Model Context Protocol (MCP)-Server für die LLM-Integration

Funktionen

• Nachrichten nach Textinhalt, Kontakt oder Datumsbereich durchsuchen

• Neueste Nachrichten abrufen

• Alle Chats/Unterhaltungen auflisten

• Alle Kontakte/Handles abrufen

• Nachrichten aus bestimmten Chats abrufen

• macOS-Kontakte nach Namen durchsuchen, mit Korrelation der iMessage-Handle-ID

Related MCP server: imessage-mcp

Voraussetzungen

• macOS (iMessage ist nur unter macOS verfügbar)

• Deno 2.x oder neuer

• Lesezugriff auf ~/Library/Messages/chat.db oder auf eine benutzerdefinierte Datenbank, die mit IMESSAGE_DB_PATH konfiguriert wurde

• Lesezugriff auf ~/Library/Application Support/AddressBook/ (für die Kontaktsuche)

Pakete

@wyattjoh/imessage

Kernbibliothek für den Zugriff auf iMessage-Daten:

deno add @wyattjoh/imessage

import { openMessagesDatabase, searchMessages } from "@wyattjoh/imessage";

const db = await openMessagesDatabase();
const results = await searchMessages(db, { query: "hello" });
db.close();

Vollständige Dokumentation ansehen

@wyattjoh/imessage-mcp

MCP-Server für die LLM-Integration:

# Run directly from JSR
deno run --allow-read --allow-env --allow-sys --allow-ffi jsr:@wyattjoh/imessage-mcp

# Or install globally
deno install --global --allow-read --allow-env --allow-sys --allow-ffi -n imessage-mcp jsr:@wyattjoh/imessage-mcp

Für die Integration in die Claude-Desktop-App fügen Sie dies zu Ihrer claude_desktop_config.json hinzu:

{
  "mcpServers": {
    "imessage": {
      "command": "deno",
      "args": [
        "run",
        "--allow-read",
        "--allow-env",
        "--allow-sys",
        "--allow-ffi",
        "jsr:@wyattjoh/imessage-mcp"
      ]
    }
  }
}

Benutzerdefinierte Nachrichtendatenbank

Setzen Sie IMESSAGE_DB_PATH, um eine schreibgeschützte SQLite-Datenbank an einem anderen Speicherort zu öffnen, z. B. eine regelmäßig aktualisierte Kopie von chat.db:

{
  "mcpServers": {
    "imessage": {
      "command": "deno",
      "args": [
        "run",
        "--allow-read",
        "--allow-env=IMESSAGE_DB_PATH",
        "--allow-sys",
        "--allow-ffi",
        "jsr:@wyattjoh/imessage-mcp"
      ],
      "env": {
        "IMESSAGE_DB_PATH": "/tmp/imessage-snapshot.sqlite"
      }
    }
  }
}

Der Prozess benötigt Lesezugriff auf die benutzerdefinierte Datei. Wenn Deno keine Berechtigung zum Lesen von IMESSAGE_DB_PATH hat oder die Variable leer oder nicht gesetzt ist, verwendet die Bibliothek ~/Library/Messages/chat.db, ohne nach einem Umgebungszugriff zu fragen.

Option 2: Aus dem Quellcode

1. Klonen Sie dieses Repository

2. Abhängigkeiten installieren:

   deno cache src/index.ts

3. Server ausführen:

   deno run --allow-read --allow-env --allow-sys --allow-ffi src/index.ts
   # Or use the task:
   deno task start

Verfügbare Werkzeuge

1. search_messages – Nachrichten mit Filtern durchsuchen

   • query (optional): Zu suchender Text

   • handle (optional): Telefonnummer oder E-Mail-Adresse zum Filtern

   • startDate (optional): ISO-Datumszeit-String für das Startdatum

   • endDate (optional): ISO-Datumszeit-String für das Enddatum

   • limit (optional): Maximale Anzahl der Ergebnisse (1–200, Standard: 100)

   • offset (optional): Seitenversatz für die Paginierung (Standard: 0)

2. get_recent_messages – Die neuesten Nachrichten abrufen

   • limit (optional): Anzahl der Nachrichten (1–100, Standard: 20)

   • offset (optional): Seitenversatz für die Paginierung (Standard: 0)

3. get_chats – Alle Unterhaltungen auflisten

   • limit (optional): Anzahl der Chats (1–200, Standard: 50)

   • offset (optional): Seitenversatz für die Paginierung (Standard: 0)

4. get_handles – Alle Kontakte/Handles abrufen

   • limit (optional): Anzahl der Handles (1–200, Standard: 100)

   • offset (optional): Seitenversatz für die Paginierung (Standard: 0)

5. get_messages_from_chat – Nachrichten aus einem bestimmten Chat abrufen

   • chatGuid (erforderlich): Die Chat-GUID

   • limit (optional): Anzahl der Nachrichten (1–200, Standard: 50)

   • offset (optional): Seitenversatz für die Paginierung (Standard: 0)

6. search_contacts – macOS-Kontakte nach Namen durchsuchen und Telefonnummern abrufen

   • firstName (erforderlich): Zu suchender Vorname (z. B. „Max“)

   • lastName (optional): Zu suchender Nachname (z. B. „Mustermann“). Wenn nicht angegeben, wird in allen Namensfeldern gesucht

   • limit (optional): Maximale Anzahl der Ergebnisse (1–200, Standard: 50)

   • offset (optional): Seitenversatz für die Paginierung (Standard: 0)

   • Gibt Kontaktinformationen mit Telefonnummern und E-Mail-Adressen zurück, die als Handle-Parameter verwendet werden können

   • Durchsucht direkt die macOS-Adressbuchdatenbank für bessere Leistung und Zuverlässigkeit

Beispiele für die Paginierung

Alle Werkzeuge unterstützen jetzt die Paginierung über die Parameter limit und offset und geben Metadaten zur Paginierung zurück:

// Get first 20 recent messages
get_recent_messages({ limit: 20, offset: 0 });

// Get next 20 recent messages (page 2)
get_recent_messages({ limit: 20, offset: 20 });

// Get first 10 chats
get_chats({ limit: 10, offset: 0 });

// Get messages 51-100 from a specific chat
get_messages_from_chat({
  chatGuid: "iMessage;-;+15551234",
  limit: 50,
  offset: 50,
});

// Search with pagination
search_messages({
  query: "meeting",
  limit: 100,
  offset: 200,
});

// Search contacts with pagination
search_contacts({
  firstName: "John",
  lastName: "Smith",
  limit: 50,
  offset: 0,
});

Antwortformat mit Paginierungs-Metadaten

Alle paginierten Werkzeuge geben Antworten jetzt in folgendem Format zurück:

{
  "data": [
    // Array of results (messages, chats, handles, etc.)
  ],
  "pagination": {
    "total": 1250, // Total number of results available
    "limit": 100, // Current page size
    "offset": 200, // Current offset
    "hasMore": true, // Whether there are more results to fetch
    "page": 3, // Current page number (1-indexed)
    "totalPages": 13 // Total number of pages
  }
}

Diese Metadaten helfen Ihnen dabei:

• Die Gesamtzahl der Ergebnisse zu ermitteln, ohne alle abzurufen

• Festzustellen, ob es weitere Seiten zum Abrufen gibt (hasMore)

• Zu berechnen, auf welcher Seite Sie sich befinden und wie viele Seiten es gibt

• Passende Paginierungs-UI-Komponenten zu erstellen

Sicherheitshinweise

• Dieser Server läuft mit schreibgeschütztem Zugriff auf die iMessage-Datenbank

• Es können keine Nachrichten gesendet oder geändert werden

• Der Server greift nur auf lokale Daten zu

Entwicklung

Dies ist ein Deno-Workspace-Monorepo. Alle Befehle, die vom Stammverzeichnis aus ausgeführt werden, wirken sich auf alle Pakete aus.

# Clone the repository
git clone https://github.com/wyattjoh/imessage-mcp.git
cd imessage-mcp

# Cache dependencies
deno cache packages/*/mod.ts

# Format all code
deno task fmt

# Lint all packages
deno task lint

# Type check all packages
deno task check

# Run tests
deno task test

# Run MCP server locally
cd packages/imessage-mcp
deno run --allow-read --allow-env --allow-sys --allow-ffi mod.ts

# Publish packages (CI/CD)
deno publish

An einzelnen Paketen arbeiten

# Work on @wyattjoh/imessage
cd packages/imessage
deno test --allow-read --allow-env --allow-ffi --allow-sys=homedir

# Work on @wyattjoh/imessage-mcp
cd packages/imessage-mcp
deno run --allow-read --allow-env --allow-sys --allow-ffi mod.ts

Lizenz

MIT