KakaoTalk Local MCP

Windows 카카오톡 PC 앱을 로컬 MCP 클라이언트와 연결하는 비공식·로컬 우선 브리지입니다. 사용자가 직접 허용한 채팅방만 다루며, 메시지 전송과 자동 답장은 기본적으로 비활성화되어 있습니다.

주요 특징

• 허용 목록에 등록한 채팅방만 접근합니다.

• 외부에는 실제 방 제목 대신 사용자가 정한 불투명 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 저장소 또는 클라우드 동기화 폴더에 올리지 않는 것을 권장합니다.

필요 환경

• 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으로 최신 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에서도 Windows와 Ubuntu, Python 3.11과 3.12 조합을 검사합니다.

제작자 표기 부탁드립니다

이 프로젝트를 사용한 글, 영상, 데모, 연구 또는 파생 프로젝트를 공개하실 때 아래처럼 제작자와 저장소를 함께 언급해 주시면 감사하겠습니다.

Made with KakaoTalk Local MCP by @Bum-Boo

MIT 라이선스가 요구하는 저작권·라이선스 고지는 반드시 유지해 주세요. 위 문구를 통한 공개 언급은 법적 조건을 추가하려는 것이 아니라, 프로젝트를 만든 사람과 원본 저장소를 찾을 수 있도록 부탁드리는 것입니다.

영감을 주신 프로젝트

다음 오픈소스 프로젝트의 아이디어와 선행 작업에서 영감을 받았습니다. 좋은 작업을 공개해 주신 제작자분들께 감사드립니다.

• kronenz/kakaotalk-mcp — Win32 창 탐색과 MCP 연결 방식

• johklo/moltbot — 기준선, 메시지 fingerprint와 전송 전 재검증

• channprj/kmsg — 로컬 별칭, 제한된 상태 관리와 fail-closed 설계

• is-theo/kakao-cli-win — Windows v2 SQLCipher 구조 연구의 출발점

참고한 revision과 라이선스 정보는 THIRD_PARTY_NOTICES.md에 기록되어 있습니다. 위 프로젝트의 코드를 그대로 번들하거나 공식 지원을 받는다는 의미는 아닙니다.

개인정보·보안·라이선스

• 개인정보 처리 경계: PRIVACY.md

• 취약점 신고와 위협 모델: SECURITY.md

• 제3자 고지: THIRD_PARTY_NOTICES.md

• 라이선스: MIT