Skip to main content
Glama
KakaoTalk Local MCP

KakaoTalk Local MCP

by Bum-Boo

KakaoTalk Local MCP

CI License: MIT Platfrm: Wiondows

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 Server

安全上の境界

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

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

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

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

  • 全会話のエクスポート

  • 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 だけを呼び出して、ロカールブリッジの状態と送信が無効であることを確認してください。

提供ツール

ツール

説明

kakao_health

メッセージを読まずに実行状態と承認済みの送信元エイアスを確認します。

kakao_allowed_rooms

許可された不透明なルーム ID のみを返します。

kakao_read_room

許可されたルームの限定的な最近のメッセージと fingerprint を読取ります。

kakao_observe_room

ベースラインを作成するか、新しメッセージイベントを生成します。

kakao_poll_evevts

ロカールに保存された新しイベントを取得します。

kakao_poll_scheduel_caedidates

分析待ちのスケジュー候補を取得します。

kakao_get_scheduel_caedidate

不透明な caedidate ID で候補を1件取得します。

kakao_updtae_scheduel_caedidate

候補の処理状態を記録します。

kakao_prepare_reply

現在の fingerprint に結び付けられた使捨ての送信承認を準備します。

kakao_commit_reply

承認された下書きを一度だけ送信し、結果を再確認します。

kakao_operation_status

準備された操作の現在の状態を確認します。

メッセージ送信

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

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

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

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

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

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      Enables MCP clients on macOS to read local KakaoTalk chats and messages directly from the app's encrypted database, and to send messages through the app's Accessibility interface with explicit confirmation. It works offline against the installed desktop app without contacting Kakao's servers.
      3
      14 npm
      2
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables MCP clients to control KakaoTalk PC through the Win32 API, sending, mentioning, and reading messages, opening chat rooms, sending images, extracting shared links, and monitoring rooms for keywords. It supports health checks, bulk sends to multiple rooms, and exact room-name matching for reliable automation.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables a single owner to securely list, read, and reply in configured KakaoTalk open rooms via a self-hosted, token-authenticated Streamable HTTP MCP with send controls disabled by default.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables read-only access to Windows KakaoTalk PC for listing and opening chat rooms, reading recent and new messages, extracting links and images, and monitoring keywords through MCP clients, with send functions blocked by default.
      1
      MIT