KakaoTalk Local MCP

Eine lokale, inoffizielle Brücke, die die Windows-KakaoTalk-PC-App mit lokalen MCP-Clients verbindet. Sie verarbeitet nur Chaträume, die der Benutzer selbst erlaubt hat; das Senden von Nachrichten und automatische Antworten sind standardmäßig deaktiviert.

[!WARNING] Dieses Projekt steht in keiner Verbindung zu Kakao Corp. und ist kein offizielles Produkt von Kakao. Funktionen können durch KakaoTalk-Updates unterbrochen werden. Bitte prüfen Sie vor der Nutzung selbst die KakaoTalk-Nutzungsbedingungen und die geltenden Gesetze.

Hauptmerkmale

• Es greift nur auf Chaträume zu, die in der Zulassungsliste registriert sind.

• Nach außen wird anstelle des tatsächlichen Raumtitels eine vom Benutzer festgelegte undurchsichtige room_id offengelegt.

• Beim ersten Beobachten wird der aktuelle Zustand als Basislinie gespeichert, sodass frühere Gespräche nicht als neue Nachrichten wiedergegeben werden.

• Doppelte Nachrichten und doppelte Vorgänge werden über Fingerprints und Idempotenzstatus blockiert.

• Das Senden von Antworten folgt der Reihenfolge prepare → 사용자 승인 → commit → readback.

• send_enabled und auto_reply_enabled sind standardmäßig false.

• Optional können Terminkandidaten lokal ausgewählt und an einen separaten Terminverwaltungsagenten übergeben werden.

• Der optionale Backend-Watcher verarbeitet nur eine explizit ausgewählte kleine Anzahl an Räumen und speichert keine Rohschlüssel oder Klartextdatenbanken als Dateien.

• Im Leerlauf werden keine KI-Modelle aufgerufen.

Related MCP server: kakaotalk-mcp

Sicherheitsgrenzen

Dieses Projekt bietet die folgenden Funktionen nicht an:

• Extraktion von KakaoTalk-Kontopasswörtern, Sitzungen oder Anmeldeinformationen

• Implementierung proprietärer Netzwerkprotokolle

• Unbegrenztes Sammeln aller Chaträume

• Export vollständiger Konversationen

• Speicherung von Roh-DB-Schlüsseln oder Klartextdatenbanken

• Massenversand von Nachrichten

• Automatische Antworten ohne Genehmigung

Setzen Sie den lokalen MCP-Server nicht direkt dem Internet oder einem öffentlichen Netzwerk aus. Es wird empfohlen, tatsächliche Konfigurationen, die Statusdatenbank, Protokolle und Chat-Aufzeichnungen nicht in Git-Repositorys oder Cloud-Synchronisierungsordner hochzuladen.

Voraussetzungen

• Windows 10 oder Windows 11

• Angemeldete KakaoTalk-PC-App

• Python 3.11 oder höher

• PowerShell

• Einen MCP-Client, der einen stdio-MCP-Server ausführen kann

Installation

Laden Sie das Repository in PowerShell herunter und führen Sie dann das Installationsskript aus.

git clone https://github.com/Bum-Boo/kakaotalk-local-mcp.git
cd kakaotalk-local-mcp
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\install-windows.ps1

Das Installationsskript erstellt ein projektspezifisches .venv und kopiert eine sichere Beispielkonfiguration nur dann, wenn keine config.json vorhanden ist.

Grundkonfiguration

config.json ist nicht im öffentlichen Repository enthalten. Starten Sie zunächst mit deaktiviertem Senden und deaktivierter Terminautomatisierung.

{
  "adapter": "win32",
  "send_enabled": false,
  "auto_reply_enabled": false,
  "schedule_automation_enabled": false,
  "backend_collector": null,
  "rooms": []
}

Chatraum registrieren

Wenn Sie den Ziel-Chatraum in genau einem separaten Fenster öffnen und danach den folgenden Befehl ausführen, können Sie ihn registrieren, ohne den Raumtitel in der Konsole anzuzeigen.

.\.venv\Scripts\hermes-kakao-mcp.exe --config .\config.json adopt-open-room --room-id self-test

Wenn nicht genau ein Chatraum geöffnet ist, wird die Konfiguration nicht geändert. room_id ist ein lokaler Alias für die Verwendung in MCP und darf vom tatsächlichen Chatraumtitel abweichen.

Prüfen Sie die Konfiguration nach dem Anwenden mit dem folgenden Befehl.

.\.venv\Scripts\hermes-kakao-mcp.exe --config .\config.json validate-config
.\scripts\doctor.cmd

MCP-Client-Verbindung

Registrieren Sie in der stdio-Serverkonfiguration Ihres MCP-Clients die folgende ausführbare Datei. Sie müssen sie durch den tatsächlichen Repository-Pfad ersetzen.

{
  "mcpServers": {
    "kakaotalk-local": {
      "command": "C:\\Windows\\System32\\cmd.exe",
      "args": [
        "/d",
        "/s",
        "/c",
        "C:\\path\\to\\kakaotalk-local-mcp\\scripts\\run-mcp.cmd"
      ]
    }
  }
}

Rufen Sie nach der Verbindung zunächst nur kakao_health auf, um den Status der lokalen Brücke und die Deaktivierung des Sendens zu überprüfen.

Verfügbare Tools

Nachrichten senden

Auch wenn ein tatsächlicher Versand erforderlich ist, halten Sie sich bitte an die folgende Reihenfolge.

1. Prüfen Sie mit kakao_read_room den aktuellen Fingerprint.

2. Zeigen Sie dem Benutzer den zu sendenden Entwurf.

3. Bereiten Sie mit kakao_prepare_reply einen einmaligen Vorgang vor.

4. Der Benutzer genehmigt den Vorgang ausdrücklich in der aktuellen Runde.

5. Rufen Sie kakao_commit_reply genau einmal auf.

6. Wenn neuere Nachrichten eingegangen sind oder das Readback-Ergebnis unklar ist, wird nicht automatisch erneut versucht.

Wenn send_enabled in der Konfiguration false ist, wird in der Commit-Phase nicht gesendet.

Optionaler Watcher

Der reguläre UI-Watcher kann wie folgt ausgeführt werden.

.\.venv\Scripts\hermes-kakao-watch.exe --once
.\.venv\Scripts\hermes-kakao-watch.exe

Den optionalen Backend-Watcher sollten Sie nur verwenden, wenn Sie separat genehmigte Raum-IDs und die aktuelle KakaoTalk-Version festgelegt haben.

{
  "backend_collector": {
    "enabled": true,
    "mode": "ram_only_v2",
    "room_ids": ["approved-room-one"],
    "max_batch_rows": 200,
    "bootstrap_retry_seconds": 30,
    "expected_client_version": "현재 검증한 버전"
  }
}

Weicht die KakaoTalk-Version vom eingestellten Wert ab, stoppt der Backend-Watcher vor dem Datenzugriff.

Entwicklung und Validierung

uv sync --extra dev
uv run ruff check .
uv run pytest
uv run python tests\smoke_mcp.py

Auch GitHub Actions prüft Kombinationen aus Windows und Ubuntu sowie Python 3.11 und 3.12.

Bitte um Nennung der Ersteller

Wenn Sie Artikel, Videos, Demos, Forschungsarbeiten oder abgeleitete Projekte veröffentlichen, die dieses Projekt verwenden, nennen Sie bitte wie unten gezeigt die Ersteller und das Repository.

Erstellt mit KakaoTalk Local MCP von @Bum-Boo

Bitte stellen Sie sicher, dass die von der MIT-Lizenz geforderten Urheberrechts- und Lizenzhinweise erhalten bleiben. Die öffentliche Nennung über den obigen Satz soll keine rechtlichen Bedingungen hinzufügen, sondern ist eine Bitte darum, dass die Person, die das Projekt erstellt hat, und das ursprüngliche Repository auffindbar bleiben.

Inspirierende Projekte

Dieses Projekt wurde von den Ideen und Vorarbeiten der folgenden Open-Source-Projekte inspiriert. Wir danken den Entwicklerinnen und Entwicklern, die ihre gute Arbeit veröffentlicht haben.

• kronenz/kakaotalk-mcp — Win32-Fenstererkennung und MCP-Anbindung

• johklo/moltbot — Basislinie, Nachrichten-Fingerprints und erneute Überprüfung vor dem Senden

• channprj/kmsg — Lokale Aliase, begrenzte Zustandsverwaltung und Fail-Closed-Design

• is-theo/kakao-cli-win — Ausgangspunkt für die Untersuchung der Windows-v2-SQLCipher-Struktur

Die referenzierten Revisionen und Lizenzinformationen sind in THIRD_PARTY_NOTICES.md dokumentiert. Dies bedeutet nicht, dass Code der oben genannten Projekte unverändert gebündelt wird oder dass offizieller Support gewährt wird.

Datenschutz · Sicherheit · Lizenz

• Datenschutzgrenzen: PRIVACY.md

• Schwachstellenmeldung und Bedrohungsmodell: SECURITY.md

• Drittanbieter-Hinweise: THIRD_PARTY_NOTICES.md

• Lizenz: MIT