<!-- default lang: ko --> <p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/badge/KatokMCP-FFCD00?style=for-the-badge&logo=kakao&logoColor=000000"> <img src="https://img.shields.io/badge/KatokMCP-FFCD00?style=for-the-badge&logo=kakao&logoColor=000000" alt="KatokMCP" height="40"> </picture> </p>

<h1 align="center">KatokMCP — AI로 카카오톡 제어하기 🤖✉️</h1>

<p align="center"> <strong>Claude Desktop / OpenClaw / Claude Code에서 동작하는 오픈소스 KakaoTalk MCP 서버</strong> <br> by 판교동돌주먹 (Pangyo Stonefist) </p>

<p align="center"> <a href="#-한국어"><img src="https://img.shields.io/badge/🇰🇷-한국어-FFCD00?style=flat-square&logo=kakao&logoColor=000000" alt="한국어" height="28"></a> <a href="#-english"><img src="https://img.shields.io/badge/🇺🇸-English-3178C6?style=flat-square&logo=typescript&logoColor=white" height="28"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-green?style=flat-square" alt="MIT License" height="28"></a> <a href="https://github.com/mwl313/KatokMCP"><img src="https://img.shields.io/github/last-commit/mwl313/KatokMCP?style=flat-square" alt="Last Commit" height="28"></a> <a href="https://github.com/mwl313/KatokMCP/actions"><img src="https://github.com/mwl313/KatokMCP/actions/workflows/ci.yml/badge.svg" alt="CI" height="28"></a> </p>

⚠️ 비공식 프로젝트입니다. 카카오와 제휴 또는 보증 관계가 아닙니다. Unofficial project. Not affiliated with or endorsed by Kakao Corp.

<br>

🇰🇷 한국어

이 프로젝트는 카카오톡의 비공개 프로토콜(LOCO)을 분석하여 구현한 결과물입니다. <br> 연구 및 교육 목적으로만 사용해 주세요. <br> 강한 힘에는 강한 책임감이 동반됩니다. <br>강력한 기능들을 책임감 있게 사용해 주세요.

🤷 그래서 이게 뭐예요?

KatokMCP를 사용하면 여러분의 AI 비서가 카카오톡을 직접 다룰 수 있게 됩니다.

• 📋 "읽지 않은 메시지가 있는 채팅방 알려줘" → AI가 채팅방 목록을 확인
• 📖 "가족 단톡방에서 오늘 무슨 얘기했어?" → AI가 메시지를 읽어줌
• ✉️ "엄마한테 저녁 7시에 도착한다고 보내줘" → AI가 메시지를 대신 전송
• 👥 "이 방에 누가 있어?" → AI가 채팅방 멤버를 알려줌

MCP(Model Context Protocol)는 AI 모델이 외부 도구와 소통하기 위한 국제 표준입니다. Claude Desktop, OpenClaw, Claude Code에서 동작을 확인했습니다. 기타 MCP 클라이언트는 호환성 표를 참고하세요.

_{<i>데모 영상: Claude Desktop에서 KakaoTalk 채팅방 조회 및 메시지 전송</i>}

✨ 주요 기능

🚀 어떻게 쓰나요?

1. 준비물

• Node.js 18 이상이 설치된 컴퓨터
• 카카오톡 계정 (이메일 + 비밀번호)
• 카카오톡 계정이 설치된 폰 (안드 IOS 상관X) (최초 1회 인증용, 이후에는 불필요)

2. 설치

#### 🚀 1분 설치 (권장)

# 글로벌 설치
npm install -g @katok-mcp/mcp-server

# 설치 마법사 실행 (5단계)
katok-mcp setup

katok-mcp setup 명령어가 다음을 자동으로 처리합니다:

1. ✅ 카카오톡 계정 입력 (AES-256-GCM 암호화 저장)
2. ✅ Device UUID 자동 생성
3. ✅ 휴대폰 인증 (최초 1회 passcode)
4. ✅ AI 비서 설정 (Claude / ChatGPT / Cursor / VS Code)
5. ✅ 메시지 전송 허용 여부

AI 비서를 재시작한 후 말해보세요:

"카톡 채팅방 목록 보여줘"

#### 상세 설치 (개발자용)

# 방법 1: npx로 바로 실행 (권장)
npx @katok-mcp/mcp-server

# 방법 2: 저장소 다운로드
# git clone https://github.com/mwl313/KatokMCP.git
# cd KatokMCP
# cd packages/loco-engine && npm install && npm run build
# cd ../mcp-server && npm install && cd ../..

3. 인증 (최초 1회)

카카오톡 보안 정책상, 새로운 기기에서 로그인하려면 휴대폰 인증이 필요합니다.

설치 마법사 사용 시: katok-mcp setup의 Step 3에서 자동으로 처리됩니다.

직접 설정 시: 환경변수 (KAKAO_EMAIL, KAKAO_PASSWORD, KAKAO_ANDROID_DEVICE_UUID)를 설정 후 MCP 서버 실행 시 자동 인증됩니다.

4. AI 비서와 연결

설치 마법사(katok-mcp setup)가 AI 비서 설정을 자동으로 완료합니다.

Claude Desktop (config 자동 생성됨):

{
  "mcpServers": {
    "katok": {
      "command": "katok-mcp",
      "args": []
    }
  }
}

OpenClaw / Claude Code:

openclaw mcp set katok -- npx -y @katok-mcp/mcp-server
claude mcp add katok -- npx -y @katok-mcp/mcp-server

📖 자세한 설정법은 [AI 서비스 연동 가이드](docs/ai-integration.md)를 참고하세요.

🛡️ 보안 안내

🏗️ 기술 구조 (간략)

KatokMCP
├── 🧠 MCP 서버          ← AI 비서와의 인터페이스
│   ├── kakao_list_chats   ← 채팅방 목록
│   ├── kakao_read_chat    ← 메시지 읽기
│   ├── kakao_send_chat    ← 메시지 전송 (opt-in)
│   └── kakao_list_members ← 멤버 조회
│
└── 🔧 LOCO 엔진          ← 카카오톡 비공개 프로토콜 구현
    ├── 인증 (Android passcode)
    ├── 암호화 (RSA + AES)
    └── 명령어 (LOGINLIST, SYNCMSG, WRITE, ...)

✅ 호환성 확인

📋 현재 상태

✅ 인증 — 카카오톡 로그인
✅ 채팅방 목록 — 모든 방 확인
✅ 메시지 읽기 — 대화 내용 확인
✅ 메시지 전송 — AI가 답장 (opt-in)
✅ 멤버 조회 — 방에 있는 사람 확인
✅ 안전장치 — 속도 제한, 감사 로그, AI 표식
✅ 설치 마법사 — 1분 설정 (katok-mcp setup)
✅ Token Caching — 재인증 불필요
✅ Credential Store — 환경변수 불필요 (AES-256-GCM 암호화)

🔮 향후 계획

📄 라이선스

MIT License — 자유롭게 사용, 수정, 배포하세요.

🙏 크레딧

• [KiwiTalk](https://github.com/KiwiTalk/KiwiTalk) — Rust 기반 LOCO 구현체. BSON 구조 분석에 큰 도움
• [OpenKakao](https://github.com/JungHoonGhae/openkakao-cli) — LOCO 프로토콜 문서
• NodeKakao — 선구적인 TypeScript 구현체 (현재 보관됨)

<br> <br>

🇺🇸 English

This project implements KakaoTalk's proprietary LOCO protocol through protocol analysis. For educational and research purposes only. With great power comes great responsibility. Use responsibly.

>

⚠️ Unofficial project. Not affiliated with or endorsed by Kakao Corp.

🤷 What is this?

KatokMCP lets Claude Desktop, OpenClaw, and Claude Code control KakaoTalk — Korea's #1 messaging app.

• 📋 "Show me chats with unread messages" → AI lists your chat rooms
• 📖 "What did my family chat about today?" → AI reads the messages
• ✉️ "Tell mom I'll be there at 7" → AI sends the message for you
• 👥 "Who's in this chat?" → AI shows the members

MCP (Model Context Protocol) is an open standard for AI models to interact with external tools. Verified on Claude Desktop, OpenClaw, and Claude Code. See compatibility table for other clients.

_{<i>Demo: AI assistant reading KakaoTalk chats and sending messages</i>}

✨ Features

🚀 Quick Start

1. Prerequisites

• Node.js 18+ on your computer
• KakaoTalk account (email + password)
• Smartphone with KakaoTalk (Android or iOS — needed once for authentication)

2. Installation

#### 🚀 1-Minute Setup (Recommended)

# Global install
npm install -g @katok-mcp/mcp-server

# Run the setup wizard
katok-mcp setup

The katok-mcp setup wizard handles everything:

1. ✅ KakaoTalk account (AES-256-GCM encrypted storage)
2. ✅ Device UUID auto-generation
3. ✅ Phone authentication (one-time passcode)
4. ✅ AI service configuration (Claude / ChatGPT / Cursor)
5. ✅ Message sending permission

Restart your AI assistant and say:

"Show me my KakaoTalk chat list"

#### Manual Installation

npx @katok-mcp/mcp-server

3. Authentication

Using the setup wizard: Handled automatically in Step 3.

Manual setup: Set environment variables (KAKAO_EMAIL, KAKAO_PASSWORD, KAKAO_ANDROID_DEVICE_UUID) and run the server.

4. Connect Your AI Assistant

Claude Desktop (auto-configured by setup wizard):

{
  "mcpServers": {
    "katok": {
      "command": "katok-mcp",
      "args": []
    }
  }
}

OpenClaw / Claude Code:

openclaw mcp set katok -- npx -y @katok-mcp/mcp-server
claude mcp add katok -- npx -y @katok-mcp/mcp-server

📖 See the [AI Integration Guide](docs/ai-integration.md) for more details.

🛡️ Security

🏗️ Architecture (Overview)

KatokMCP
├── 🧠 MCP Server          ← AI assistant interface
│   ├── kakao_list_chats   ← List chat rooms
│   ├── kakao_read_chat    ← Read messages
│   ├── kakao_send_chat    ← Send messages (opt-in)
│   └── kakao_list_members ← List members
│
└── 🔧 LOCO Engine         ← KakaoTalk protocol implementation
    ├── Auth (Android passcode)
    ├── Encryption (RSA + AES)
    └── Commands (LOGINLIST, SYNCMSG, WRITE, ...)

✅ Compatibility

📋 Current Status

✅ Auth — KakaoTalk login
✅ Chat List — All rooms visible
✅ Read Messages — View conversation history
✅ Send Messages — AI replies (opt-in)
✅ List Members — Who's in a room
✅ Safety — Rate limiting, audit log, AI prefix
✅ Setup Wizard — 1-minute automated setup
✅ Token Caching — No re-authentication needed
✅ Credential Store — AES-256-GCM encrypted, no env vars required

🔮 Roadmap

📄 License

MIT License — free to use, modify, and distribute.

🙏 Credits

• [KiwiTalk](https://github.com/KiwiTalk/KiwiTalk) — Rust-based LOCO implementation. Invaluable for BSON structure analysis
• [OpenKakao](https://github.com/JungHoonGhae/openkakao-cli) — LOCO protocol documentation
• NodeKakao — Pioneering TypeScript implementation (archived)