Mac Messages Host

Die gesamte Apple-Messages-Historie (iMessage/SMS) deines Macs, schreibgeschützt, für KI-Agenten — ein gebündeltes Tool über REST/OpenAPI und Streamable-HTTP-MCP.

• Ein Tool, gebündelte Anfragen: Ein einzelnes messages(requests: str)-Tool nimmt ein JSON-Array mit Anfragen entgegen und gibt ein passendes JSON-Array mit Antworten zurück — ein Aufruf erledigt viele unabhängige Vorgänge. Wird identisch über REST (POST /api/messages) und MCP (/mcp/) bereitgestellt.

• Von Grund auf schreibgeschützt: Die Datenbank wird mit SQLite mode=ro geöffnet; es gibt keinen Schreibpfad. Es kann nichts gesendet, geändert oder gelöscht werden.

• Moderne macOS-Inhaltsdekodierung: In attributedBody-Typedstream-Blobs (Ventura+) gespeicherter Nachrichtentext und Bearbeitungsverlauf in message_summary_info-Plists werden transparent dekodiert.

• Automatisch generierter Tool-Prompt: Der für KI-Agenten bestimmte Prompt wird aus den Pydantic-Modellen generiert (~615 gpt-4o-Token, mit tiktoken gezählt und durch einen Test erzwungen); ein tool_prompt.md-Snapshot wird durch einen Drift-Test synchron gehalten.

Install

Erfordert Python 3.11+ unter macOS.

pip install .            # or: pip install -e . for development
mmhost info              # permission check + database status
mmhost start             # serve API + MCP on http://127.0.0.1:8761

macOS-Berechtigungen (wichtig)

~/Library/Messages/chat.db ist durch macOS TCC geschützt. Der Prozess, der mmhost ausführt, benötigt vollen Festplattenzugriff:

Systemeinstellungen → Datenschutz & Sicherheit → Voller Festplattenzugriff → aktiviere deine Terminal-App (oder was auch immer den Server startet) und starte sie anschließend neu.

mmhost info zeigt dir sofort, ob die Datenbank lesbar ist.

Related MCP server: imessage-mcp

Endpunkte

Authentifizierung

Authorization: Bearer <token> wenn admin_token konfiguriert ist (persistierte Konfiguration, MMHOST_ADMIN_TOKEN oder --admin-token). Ohne konfiguriertes Token ist der Zugriff offen — sicher, da der Server standardmäßig an 127.0.0.1 bindet.

Anfragearten

• get_info — Datenbankstatus, Zähler, Zeitbereich der Historie

• get_chats — Unterhaltungen nach letzter Aktivität (Filter, Paginierung)

• get_chat — Transkript eines Chats (älter über before)

• get_recent — neueste Nachrichten aus allen Chats (Polling über since)

• search_messages — Groß-/Kleinschreibung insensible Substring-Suche über die Nachrichteninhalte

Siehe tool_prompt.md für die exakte KI-Dokumentation (aus den Modellen generiert).

Beispiel

curl -s http://127.0.0.1:8761/api/messages \
  -H 'Content-Type: application/json' \
  -d '{"requests": "[{\"kind\":\"list_chats\",\"limit\":3}]"}'

MCP-Client-Konfiguration

{
  "mcpServers": {
    "mac-messages": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:8761/mcp/"
    }
  }
}

Konfiguration

Wird im spezifischen Plattform-Konfigurationsverzeichnis gespeichert (~/Library/Application Support/mac_messages_host/config.json unter macOS); du kannst den Speicherort mit MMHOST_CONFIG übersteuern. Nur Servereinstellungen — siehe example.env.

Entwicklung

pip install -e '.[dev]'
pytest
# after changing request models:
python -m tests.regenerate_tool_prompt

Architektur folgt dem oWoHo-AI-Toole-Server-Muster (reine Kernbibliothek + abgeleitete FastAPI/FastMCP/CLI-Schnittstellen), wie reddit_tool_server und obsidian_ai_miniserver.

Lizenz

MIT — siehe LICENSE.md.