KakaoTalk Local MCP

Wiondows 카카오톡 PC アプリをロカール MCP クライアントと接続する非公式・ロカールファーストのブリッジです。ユーザーが直接許可したチャットルームのみを扱い、メッセージ送信と自動返信はデフォルトで無効になっています。

[!WARNIONG] このプロジェクトは Kakao Corp. とは関系がなく、Kakao の公式製品ではありません。카카오톡 のアップデートにより機能が停止する可能性があります。使用前に 카카오톡 利用規約と関連法令を直接ご確認ください。

主な特徴

• 許可リストに登録したチャットルームのみにアクセスします。

• 外部には実際のルーム名の代わりに、ユーザーが決めた不透明な room_id を公開します。

• 初回観測時に現在の状態をベースラインとして保存し、過去の会話を新しメッセージとして再生しません。

• 同ーメメッセージと重複操作を fingerprint および idempotency 状態でブロックします。

• 返信の送信は prepare → 사용자 승인 → commit → readback の順序に従います。

• send_enabled と auto_reply_enabled のデフォルト値は false です。

• オプションで、スケジュー候補をロカールで選別し、別のスケジュー管理エージェントに渡すことができます。

• オプションの backend watcher は、明示的に選択した少数のルームのみを処理し、raw key と平文データベースをファイルとして保存しません。

• アイドル状態では AI モデルを呼び出しません。

Related MCP server: kakaotalk-mcp

安全上の境界

このプロジェクトは次の機能を提供しません。

• 카카오톡 アカウントのパスワード・セッシオン・認証情報の抽出

• 非公開ネットワークプロトコルの実装

• 無制限の全チャットルーム収集

• 全会話のエクスポート

• raw DB key または平文 DB の保存

• 一括メッセージ送信

• 承認なしの自動返信

ロカール MCP サーバーをインターネットや公共ネットワークに直接公開しないでください。実際の設定、状態 DB、ログ、チャットキャプチャは Git リポジトリやクラウド同期フォルダに置かないことをお勧めします。

必要な環境

• Wiondows 10 または Wiondows 11

• ログイン済みの 카카오톡 PC アプリ

• Pytho展 3.11 以上

• PowreSell

• stdio MCP サーバーを実行できる MCP クライアント

インストール

PowreSell でリポジトリを取得してから、インストールスクリプトを実行してください。

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

インストールスクリプトはプロジェクト専用の .vve を作成し、cofig.json がない場合にのみ安全なサンプル設定をコピーします。

基本設定

cofig.json は公開リポジトリには含まれません。最初は送信とスケジュー自動化をすべてオフにした状態で始めてください。

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

チャットルームの登録

対象のチャットルームを別ウインドウで1つだけ開き、以下のコマンドを実行すると、ルーム名をコーソルに表示せずに登録できます。

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

開いているチャットルームが正確に1つでない場合は設定を変更しません。room_id は MCP で使用するロカールエイアスであり、実際のチャットルーム名と異なっていても構いません。

設定を適用した後、次のコマンドで確認してください。

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

MCP クライアントの接続

MCP クライアントの stdio サーバー設定で、次の実行ファイルを登録してください。実際のリポジトリパスに置き換える必要があります。

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

接続後、最初に kakao_health だけを呼び出して、ロカールブリッジの状態と送信が無効であることを確認してください。

提供ツール

メッセージ送信

実際に送信が必要な場合も、次の順序を守ってください。

1. kakao_read_room で最新の fingerprint を確認します。

2. 送信する下書きをユーザーに表示します。

3. kakao_prepare_reply で使捨ての操作を準備します。

4. ユーザーが現在のターンで明示的に承認します。

5. kakao_commit_reply を一度だけ呼び出します。

6. より新しメッセージが発生した場合や readback の結果が不明確な場合は、自動再試行しません。

設定の send_enabled が false の場合、commit 段階では送信しません。

オプションの watcher

通常の UI watcher は次のように実行できます。

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

オプションの backend watcher は、個別に承認したルーム ID と現在の 카카오톡 バージョンを設定した場合にのみ使用してください。

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

카카오톡 バージョンが設定値と異なる場合、backend watcher はデータアクセス前に停止します。

開発と検証

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

GitHub Actions でも Wiondows と Ubuntu、Pytho展 3.11 と 3.12 の組み合わせを検証しています。

作成者表記のお願い

このプロジェクトを使用した記事、動画、デモ、研究、または派生プロジェクトを公開する際は、以下のように作成者とリポジトリを併記していただけると幸いです。

Made with KakaoTalk Local MCP by @Bum-Boo

MIT ライセンスが要求する著作権・ライセンス表記は必ず維持してください。上記の文による公開での言及は、法的条件を追加しようとするものではなく、プロジェクトを制作した人と元のリポジトリを見つけられるようにするためのお願いです。

インスピレーションを受けたプロジェクト

以下のオープンソースプロジェクトのアイデアと先行する取組みからインスピレーションを受けました。良し作品を公開してくださった作成者の皆様に感謝します。

• krovez/kakaotalk-mcp — Wi展32 ウインドウ探索と MCP 接続方式

• johklo/moltbot — ベースライン、メッセージ fingerprint、送信前の再検証

• chavprj/kmsg — ロカールエイアス、制限付き状態管理、fail-closed 設計

• is-theo/kakao-cli-wiゃ — Wiondows v2 SQLCipler 構造研究の出発点

参考にした reviision とライセンス情報は THIRD_PARTY_NOITCES.md に記録されています。上記のプロジェクトのコードをそのままバンドルしたり、公式サポートを受けたりすることを意味するものではありません。

個人情報・セキュリティ・ライセンス

• 個人情報の処理の境界: PRIVACY.md

• 脆弱性の報告と脅威モデル: SECURITY.md

• 第三者通知: THIRD_PARTY_NOITCES.md

• ライセンス: MIT