KakaoTalk Local MCP

将 Windows 카카오톡 PC 应用连接到本地 MCP 客户端的非官方、本地优先桥接器。它只处理用户明确允许的聊天室，并且默认禁用消息发送和自动回复。

[!WARNING] 本项目与 Kakao Corp. 无关，也不是 Kakao 的官方产品。该功能可能因 카카오톡 更新而停止工作。使用前请自行确认 카카오톡 使用条款及相关法律法规。

主要特点

• 仅访问已加入允许列表的聊天室。

• 对外暴露的是用户自行指定的不透明 room_id，而不是实际聊天室名称。

• 首次观察时将当前状态保存为基线，不会把过去的对话重放为新消息。

• 通过指纹和幂等状态阻止重复消息和重复操作。

• 回复发送遵循 prepare → 사용자 승인 → commit → readback 的顺序。

• send_enabled 和 auto_reply_enabled 的默认值均为 false。

• 可选地在本地筛选出日程候选，并将其传递给单独的日程管理代理。

• 可选的 backend watcher 仅处理明确选中的少数聊天室，并且不会将 raw key 和明文数据库保存为文件。

• 空闲状态下不会调用 AI 模型。

Related MCP server: kakaotalk-mcp

安全边界

本项目不提供以下功能。

• 提取 카카오톡 账号密码、会话、认证信息

• 实现非公开网络协议

• 无限制地收集所有聊天室

• 导出全部对话

• 保存 raw DB key 或明文数据库

• 批量发送消息

• 未经批准的自动回复

请勿将本地 MCP 服务器直接暴露到互联网或公共网络。建议不要将实际配置、状态数据库、日志和聊天截图上传到 Git 仓库或云同步文件夹。

环境要求

• Windows 10 或 Windows 11

• 已登录的 카카오톡 PC 应用

• Python 3.11 及以上

• PowerShell

• 能够运行 stdio MCP 服务器的 MCP 客户端

安装

在 PowerShell 中克隆仓库后，请运行安装脚本。

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

安装脚本会创建项目专用的 .venv，并且仅在不存在 config.json 时复制一份安全的示例配置。

基本设置

config.json 不包含在公开仓库中。请一开始就在发送和日程自动化均关闭的状态下开始。

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

注册聊天室

请只将目标聊天室作为单独窗口打开一个，然后运行以下命令，即可在不向控制台显示聊天室名称的情况下完成注册。

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

如果打开的聊天室不是恰好一个，就不会更改设置。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 确认最新的指纹。

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

仅在已设置另行批准的聊天室 ID 和当前 카카오톡 版本时，才请使用可选的 backend watcher。

{
  "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 也会检查 Windows 与 Ubuntu、Python 3.11 与 3.12 的组合。

请注明作者

如果您公开使用本项目的文章、视频、演示、研究或衍生项目，希望能像下面这样同时提及作者和仓库，不胜感激。

Made with KakaoTalk Local MCP by @Bum-Boo

请务必保留 MIT 许可证要求的版权和许可声明。通过上述文字进行的公开提及，并不是为了增加法律条件，而是希望让人们能够找到项目的创建者和原始仓库。

灵感来源项目

以下开源项目的想法和先行工作给了我灵感。感谢公开这些优秀作品的作者们。

• kronenz/kakaotalk-mcp — Win32 窗口遍历与 MCP 连接方式

• johklo/moltbot — 基线、消息指纹与发送前重新验证

• channprj/kmsg — 本地别名、受限状态管理与 fail-closed 设计

• is-theo/kakao-cli-win — Windows v2 SQLCipher 结构研究的起点

所参考的 revision 和许可证信息记录在 THIRD_PARTY_NOTICES.md 中。这并不意味着原样打包上述项目的代码，或获得其官方支持。

隐私·安全·许可证

• 隐私处理边界： PRIVACY.md

• 漏洞报告与威胁模型： SECURITY.md

• 第三方声明： THIRD_PARTY_NOTICES.md

• 许可证： MIT