KakaoTalk Local MCP

An unofficial, local-first bridge that connects the Windows KakaoTalk PC app to local MCP clients. It only handles chat rooms that the user has explicitly allowed, and message sending and automatic replies are disabled by default.

[!WARNING] This project is not affiliated with Kakao Corp. and is not an official Kakao product. Features may stop working depending on KakaoTalk updates. Before using it, please review the KakaoTalk terms of service and applicable laws yourself.

Key Features

• Only accesses chat rooms on the allowlist.

• To the outside, exposes the opaque room_id chosen by the user instead of the actual room title.

• Stores the current state as a baseline on first observation so past conversations are not replayed as new messages.

• Blocks identical messages and duplicate operations using fingerprint and idempotency state.

• Sending replies follows the sequence prepare → 사용자 승인 → commit → readback.

• send_enabled and auto_reply_enabled default to false.

• Can optionally filter schedule candidates locally and pass them to a separate schedule management agent.

• The optional backend watcher processes only a small number of explicitly selected rooms and does not save raw keys or plaintext databases as files.

• Does not call AI models while idle.

Related MCP server: KatokMcp

Safety Boundaries

This project does not provide the following:

• Extraction of KakaoTalk account passwords, sessions, or authentication credentials

• Implementation of private network protocols

• Unlimited collection of all chat rooms

• Export of entire conversations

• Saving raw DB keys or plaintext DBs

• Bulk message sending

• Automatic replies without approval

Do not expose the local MCP server directly to the internet or a public network. We recommend that you do not upload actual configuration, state DBs, logs, or chat captures to a Git repository or a cloud sync folder.

Requirements

• Windows 10 or Windows 11

• A logged-in KakaoTalk PC app

• Python 3.11 or later

• PowerShell

• An MCP client that can run stdio MCP servers

Installation

In PowerShell, clone the repository and run the installation script.

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

The installation script creates a project-specific .venv and copies a safe example configuration only when config.json does not exist.

Basic Configuration

config.json is not included in the public repository. Start with both sending and schedule automation turned off.

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

Registering a Chat Room

Open exactly one target chat room in a separate window, then run the command below to register it without displaying the room title in the console.

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

If there is not exactly one open chat room, the settings are not changed. room_id is a local alias used for MCP and does not have to match the actual chat room title.

After applying the settings, verify with the following command.

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

MCP Client Connection

In the stdio server settings of your MCP client, register the following executable. Replace it with your actual repository path.

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

After connecting, first call only kakao_health to check the local bridge status and confirm that sending is disabled.

Provided Tools

Sending Messages

Even when actual sending is needed, follow this order.

1. Check the latest fingerprint with kakao_read_room.

2. Show the user the draft to be sent.

3. Prepare a one-time operation with kakao_prepare_reply.

4. The user explicitly approves in the current turn.

5. Call kakao_commit_reply exactly once.

6. If newer messages have appeared or the readback result is unclear, do not retry automatically.

If send_enabled is false in the configuration, nothing is sent at the commit stage.

Optional Watcher

The regular UI watcher can be run as follows.

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

Use the optional backend watcher only when separately approved room IDs and the current KakaoTalk version are configured.

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

If the KakaoTalk version differs from the configured value, the backend watcher stops before accessing data.

Development and Verification

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

GitHub Actions also checks the combinations of Windows and Ubuntu with Python 3.11 and 3.12.

Please Credit the Creator

When you publicly share writing, videos, demos, research, or derivative projects that use this project, we would appreciate it if you would mention the creator and the repository together as shown below.

Made with KakaoTalk Local MCP by @Bum-Boo

Please keep the copyright and license notices required by the MIT License. The public attribution requested above is not intended to add legal conditions; it is simply a request so that the people who made the project and the original repository can be found.

Inspiring Projects

This project was inspired by the ideas and prior work of the following open source projects. We thank the creators for sharing their excellent work.

• kronenz/kakaotalk-mcp — Win32 window discovery and MCP connection approach

• johklo/moltbot — Baseline, message fingerprints, and re-verification before sending

• channprj/kmsg — Local aliases, limited state management, and fail-closed design

• is-theo/kakao-cli-win — Starting point for research into the Windows v2 SQLCipher structure

The revisions consulted and license information are recorded in THIRD_PARTY_NOTICES.md. This does not mean that the code of the above projects is bundled as-is or that official support is provided.

Privacy, Security, and License

• Privacy handling boundaries: PRIVACY.md

• Vulnerability reporting and threat model: SECURITY.md

• Third-party notices: THIRD_PARTY_NOTICES.md

• License: MIT