<!-- 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"> <<<<<<< HEAD <strong>Claude Desktop / OpenClaw / Claude Code에서 동작하는 오픈소스 KakaoTalk MCP 서버</strong> <br> by 판교동돌주먹 (Pangyo Stonefist)

<strong>AI (Claude, ChatGPT, Gemini)가 카카오톡을 읽고, 답장하고, 관리할 수 있게 해주는 오픈소스 MCP 서버</strong>

feature/http-transport </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> <<<<<<< HEAD <p align="center"> <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. ======= <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> </p>

---

feature/http-transport

<br>

🇰🇷 한국어

<<<<<<< HEAD

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

feature/http-transport

---

🤷 그래서 이게 뭐예요?

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

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

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

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

MCP(Model Context Protocol)는 AI 모델이 외부 도구와 소통하기 위한 국제 표준입니다. Claude, ChatGPT, Gemini, OpenClaw 등 모든 주요 AI 서비스와 호환됩니다.

feature/http-transport

---

✨ 주요 기능

기능	설명
채팅방 목록 보기	모든 채팅방, 읽지 않은 메시지 수, 멤버, 마지막 메시지
메시지 읽기	특정 채팅방의 최근 메시지 내역
메시지 전송 🤖	AI가 대신 답장 (opt-in 필수, 자동 🤖 표식)
멤버 조회	채팅방에 누가 있는지 확인

---

🚀 어떻게 쓰나요?

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 비서를 재시작한 후 말해보세요:

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

상세 설치 (개발자용)

<<<<<<< HEAD
# 방법 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 ../..
=======
# 저장소 다운로드
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 ../..
>>>>>>> feature/http-transport

3. 인증 (최초 1회)

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

<<<<<<< HEAD

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

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

4. AI 비서와 연결

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

Claude Desktop (config 자동 생성됨):

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

직접 설정 시 (환경변수):

① 환경변수 설정

set KAKAO_EMAIL=your@email.com
set KAKAO_PASSWORD=your_password
set KAKAO_ANDROID_DEVICE_UUID=0000...0001  # 아무 64자리 hex
set KAKAO_CONFIRM_ANDROID_REGISTRATION=YES

② 인증 실행

cd poc/03-loginlist
npm run auth-android-register

③ passcode 입력 (1회, 60초 내)

Enter this one-time code in the KakaoTalk app: 0123 (58s)

→ 휴대폰 카카오톡 앱을 열고 표시된 번호를 입력하세요.

④ 완료! 이후에는 자동 로그인됩니다.

4. MCP 서버 실행

# 방법 A: katok-mcp-server 명령어 (글로벌 설치 후)
katok-mcp-server

# 방법 B: npx 직접 실행
npx -y @katok-mcp/mcp-server

# 방법 C: 개발 모드
cd packages/mcp-server
set KAKAO_EMAIL=your@email.com
set KAKAO_PASSWORD=your_password  
set KAKAO_ANDROID_DEVICE_UUID=0000...0001
npm run dev

5. AI 비서와 연결

Claude Desktop (claude_desktop_config.json):

feature/http-transport

{
  "mcpServers": {
    "katok": {
<<<<<<< HEAD
      "command": "katok-mcp",
      "args": []
=======
      "command": "npx",
      "args": ["-y", "@katok-mcp/mcp-server"],
      "env": {
        "KAKAO_EMAIL": "your@email.com",
        "KAKAO_PASSWORD": "your_password",
        "KAKAO_ANDROID_DEVICE_UUID": "0000...0001"
      }
>>>>>>> feature/http-transport
    }
  }
}

<<<<<<< HEAD OpenClaw / Claude Code:

openclaw mcp set katok -- npx -y @katok-mcp/mcp-server
=======
> 💡 **팁:** `katok-mcp setup` 마법사가 이 설정을 자동으로 생성해줍니다!

**OpenClaw / Claude Code:**
```bash
>>>>>>> feature/http-transport
claude mcp add katok -- npx -y @katok-mcp/mcp-server

📖 자세한 설정법은 AI 서비스 연동 가이드를 참고하세요.

---

🛡️ 보안 안내

항목	내용
메시지 전송	처음에는 비활성화되어 있음. KAKAO_ALLOW_WRITE=YES 설정해야 전송 가능
AI 표식	AI가 보낸 메시지에는 자동으로 🤖 이모지가 붙음 (비활성화 가능)
<<<<<<< HEAD
자격 증명 저장	katok-mcp setup으로 입력한 계정 정보는 AES-256-GCM 암호화 저장. AI 클라이언트 설정 파일에는 비밀번호가 저장되지 않음
=======
토큰 저장	비밀번호를 안전하게 저장하려면 kakao-mcp store-credentials 명령어 사용 (AES-256-GCM 암호화)

feature/http-transport | 읽기 전용 기본값 | 메시지를 보내지 않고 읽기만 함 | | 속도 제한 | 초당 3회로 요청 제한 (남용 방지) | | 감사 로그 | 모든 명령어 실행 내역 기록 (dev 모드: 전체, prod 모드: 해시만) |

---

🏗️ 기술 구조 (간략)

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

<<<<<<< HEAD

✅ 호환성 확인

AI 서비스	상태	비고
Claude Desktop (Windows/macOS)	✅ 동작 확인	katok-mcp setup 자동 설정
OpenClaw	✅ 동작 확인	openclaw mcp set katok
Claude Code (CLI)	✅ 동작 확인	claude mcp add katok
ChatGPT Desktop	❓ 미확인	MCP 기능 실험적 (별도 설정 필요)
Cursor / VS Code	❓ 미확인	설정 가능하나 실제 테스트 필요
ChatGPT Web	❌ 불가능	MCP 미지원 (HTTP Transport 필요)
=======
기술적으로 궁금한 점은 PLAN.md와 PROTOCOL_VERIFIED.md를 참고하세요.

feature/http-transport

---

📋 현재 상태

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

---

<<<<<<< HEAD

🔮 향후 계획

단계	작업	우선순위
G	npm publish 완료 ✅	—
H	GitHub 공개 + awesome-mcp-servers 등록	🟡
I	HTTP Transport (ChatGPT Web 호환)	🟢
J	Session Daemon (멀티 클라이언트, 실시간 Push)	🟢
K	멀티 계정, Docker 이미지, 채팅방 검색	💡

---

=======

feature/http-transport

📄 라이선스

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

---

🙏 크레딧

• KiwiTalk — Rust 기반 LOCO 구현체. BSON 구조 분석에 큰 도움
• OpenKakao — LOCO 프로토콜 문서
• NodeKakao — 선구적인 TypeScript 구현체 (현재 보관됨)

---

<br> <br>

🇺🇸 English

<<<<<<< HEAD

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. ======= This project implements KakaoTalk's proprietary LOCO protocol through protocol analysis. For educational and research purposes only.

feature/http-transport

---

🤷 What is this?

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

KatokMCP lets your AI assistant control KakaoTalk — Korea's #1 messaging app.

feature/http-transport

• 📋 "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

<<<<<<< HEAD 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>}

MCP (Model Context Protocol) is an open standard for AI models to interact with external tools. Supported by Claude, ChatGPT, Gemini, OpenClaw, and more.

feature/http-transport

---

✨ Features

Feature	Description
List Chats	All chat rooms with unread counts, members, last message
Read Messages	Recent messages from any chat room
Send Messages 🤖	AI sends replies on your behalf (opt-in required, auto 🤖 prefix)
List Members	See who's in a chat room

---

🚀 Quick Start

1. Prerequisites

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

<<<<<<< HEAD

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):

2. Install

git clone https://github.com/mwl313/KatokMCP.git
cd KatokMCP

# Install packages
cd packages/loco-engine && npm install && npm run build
cd ../mcp-server && npm install
cd ../..

3. Authentication (first time only)

KakaoTalk security requires phone verification for new devices.

① Set environment variables

set KAKAO_EMAIL=your@email.com
set KAKAO_PASSWORD=your_password
set KAKAO_ANDROID_DEVICE_UUID=0000...0001  # any 64-char hex
set KAKAO_CONFIRM_ANDROID_REGISTRATION=YES

② Run authentication

cd poc/03-loginlist
npm run auth-android-register

③ Enter passcode in the KakaoTalk app (60s window)

Enter this one-time code in the KakaoTalk app: 9418 (58s)

→ Open KakaoTalk on your phone and enter the code.

④ Done! Subsequent logins are automatic.

4. Run the MCP Server

cd packages/mcp-server
set KAKAO_EMAIL=your@email.com
set KAKAO_PASSWORD=your_password
set KAKAO_ANDROID_DEVICE_UUID=0000...0001
npm run dev

5. Connect Your AI Assistant

Claude Desktop (claude_desktop_config.json):

feature/http-transport

{
  "mcpServers": {
    "katok": {
<<<<<<< HEAD
      "command": "katok-mcp",
      "args": []
=======
      "command": "node",
      "args": ["C:\\path\\to\\KatokMCP\\packages\\mcp-server\\dist\\index.js"],
      "env": {
        "KAKAO_EMAIL": "your@email.com",
        "KAKAO_PASSWORD": "your_password",
        "KAKAO_ANDROID_DEVICE_UUID": "0000...0001"
      }
>>>>>>> feature/http-transport
    }
  }
}

OpenClaw / Claude Code:

<<<<<<< HEAD
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 for more details. ======= claude mcp add katok -- node C:\path\to\KatokMCP\packages\mcp-server\dist\index.js

> 📖 **See the [AI Integration Guide](docs/ai-integration.md) for more details.** (coming soon)
>>>>>>> feature/http-transport

---

## 🛡️ Security

| Item | Detail |
|------|--------|
| **Message Sending** | Disabled by default. Set `KAKAO_ALLOW_WRITE=YES` to enable |
| **AI Prefix** | Bot messages automatically get 🤖 prefix (configurable) |
<<<<<<< HEAD
| **Credential Storage** | Account credentials encrypted via AES-256-GCM. Password is never stored in AI client config files |
=======
| **Token Storage** | AES-256-GCM encrypted credential storage available via `kakao-mcp store-credentials` |
>>>>>>> feature/http-transport
| **Read-Only by Default** | Won't send anything unless you explicitly allow it |
| **Rate Limiting** | Max 3 requests per second (abuse prevention) |
| **Audit Log** | Full detail in dev mode, hashes only in production |

---

## 🏗️ 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, ...)

---

<<<<<<< HEAD
## ✅ Compatibility

| AI Service | Status | Notes |
|------------|:------:|-------|
| **Claude Desktop** (Windows/macOS) | ✅ Verified | Auto-configured via setup wizard |
| **OpenClaw** | ✅ Verified | openclaw mcp set katok |
| **Claude Code (CLI)** | ✅ Verified | claude mcp add katok |
| **ChatGPT Desktop** | ❓ Unverified | MCP feature experimental |
| **Cursor / VS Code** | ❓ Unverified | Configurable, untested |
| **ChatGPT Web** | ❌ Not supported | Requires HTTP Transport (planned) |

---

=======
>>>>>>> feature/http-transport
## 📋 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 <<<<<<< HEAD ✅ Setup Wizard — 1-minute automated setup ✅ Token Caching — No re-authentication needed ✅ Credential Store — AES-256-GCM encrypted, no env vars required

feature/http-transport

---

<<<<<<< HEAD
## 🔮 Roadmap

| Phase | Task | Priority |
|:-----:|------|:--------:|
| **G** | npm publish ✅ | Done |
| **H** | GitHub public + awesome-mcp-servers | 🟡 |
| **I** | HTTP Transport (ChatGPT Web support) | 🟢 |
| **J** | Session Daemon (multi-client, realtime push) | 🟢 |
| **K** | Multi-account, Docker image, chat search | 💡 |

---

=======
>>>>>>> feature/http-transport
## 📄 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)