KakaoTalk Local MCP

Неофициальный локальный мост, соединяющий приложение KakaoTalk PC для Windows с локальным MCP-клиентом. Он работает только с чат-комнатами, явно разрешёнными пользователем; отправка сообщений и автоматические ответы по умолчанию отключены.

[!WARNING] Этот проект не связан с Kakao Corp. и не является официальным продуктом Kakao. После обновлений KakaoTalk его функции могут перестать работать. Перед использованием самостоятельно проверьте условия использования KakaoTalk и применимое законодательство.

Основные возможности

• Доступ осуществляется только к чат-комнатам, добавленным в список разрешённых.

• Снаружи вместо реального названия комнаты раскрывается непрозрачный room_id, заданный пользователем.

• При первом наблюдении текущее состояние сохраняется как базовая линия, поэтому прошлые диалоги не воспроизводятся как новые сообщения.

• Одинаковые сообщения и повторные операции блокируются с помощью fingerprint и состояния идемпотентности.

• Отправка ответов следует порядку prepare → 사용자 승인 → commit → readback.

• По умолчанию значения send_enabled и auto_reply_enabled равны false.

• При желании можно локально отбирать кандидатов расписания и передавать их отдельному агенту управления расписанием.

• Опциональный backend watcher обрабатывает только небольшое количество явно выбранных комнат и не сохраняет raw key и базу данных в открытом виде в файлы.

• В состоянии бездействия AI-модели не вызываются.

Related MCP server: KatokMcp

Границы безопасности

Этот проект не предоставляет следующие функции.

• Извлечение пароля, сессии и данных аутентификации учётной записи KakaoTalk

• Реализацию приватных сетевых протоколов

• Неограниченный сбор всех чат-комнат

• Экспорт всех диалогов

• Сохранение raw DB key или базы данных в открытом виде

• Массовую отправку сообщений

• Автоматические ответы без подтверждения

Не открывайте локальный MCP-сервер напрямую в интернет или публичную сеть. Рекомендуется не загружать реальные настройки, базу данных состояния, журналы и снимки чатов в Git-репозиторий или папку облачной синхронизации.

Требования к окружению

• Windows 10 или Windows 11

• Приложение KakaoTalk PC, в которое выполнен вход

• Python 3.11 и выше

• PowerShell

• MCP-клиент, поддерживающий запуск stdio 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-клиента

В настройках stdio-сервера MCP-клиента зарегистрируйте следующий исполняемый файл. Не забудьте заменить его на фактический путь к репозиторию.

{
  "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. Проверьте актуальный fingerprint с помощью 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

Опциональный backend watcher следует использовать только в том случае, если заданы отдельно одобренные ID комнат и текущая версия KakaoTalk.

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

Если версия KakaoTalk отличается от заданного значения, 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. Публичное упоминание с помощью приведённой выше фразы не добавляет юридических условий; это просьба, позволяющая найти создателей проекта и исходный репозиторий.

Проекты, вдохновившие нас

Мы вдохновлялись идеями и предыдущими наработками следующих open-source проектов. Благодарим авторов за то, что они поделились своими отличными работами.

• kronenz/kakaotalk-mcp — подход к поиску окон Win32 и подключению MCP

• johklo/moltbot — базовая линия, fingerprint сообщений и повторная проверка перед отправкой

• channprj/kmsg — локальные псевдонимы, ограниченное управление состоянием и fail-closed проектирование

• is-theo/kakao-cli-win — отправная точка для исследования структуры Windows v2 SQLCipher

Рассмотренные ревизии и сведения о лицензиях указаны в THIRD_PARTY_NOTICES.md. Это не означает, что код указанных проектов встроен в проект без изменений или что предоставляется официальная поддержка.

Конфиденциальность, безопасность и лицензия

• Границы обработки персональных данных: PRIVACY.md

• Сообщение об уязвимостях и модель угроз: SECURITY.md

• Уведомления третьих сторон: THIRD_PARTY_NOTICES.md

• Лицензия: MIT