kakao-channel-chat

Unofficial. This is a reverse engineering of the undocumented internal API of the Kakao Channel Manager Center (business chat, internal codename "rocket"). It is not an official Kakao product; the spec may break with no notice and may violate Kakao's Terms of Use. Use it for automating a channel you own, at your own responsibility. See DISCLAIMER for details.

A Node toolkit for handling Kakao Channel chats in code by reusing your logged-in browser session. Available in three forms: API library · CLI · MCP server. The only external runtime dependency is the MCP SDK (the library/CLI have zero dependencies).

What it does

• ✅ Login state check & unlimited token refresh (session never disconnects)

• ✅ Chat room list + read/unread distinction + room deep links

• ✅ Conversation history lookup (distinguishes our/customer/system messages, extracts links)

• ✅ Mark as read, send messages (reply)

• ✅ Real-time new message monitoring (SSE / polling)

• ✅ Always-on daemon (automatic token renewal + keepalive + monitoring + optional auto-reply)

• ✅ MCP server — use it as a tool in Claude/Cursor, etc.

Related MCP server: @chatmaid/mcp

How it works

The Kakao Channel chat API (business.kakao.com/api/*) is authenticated using only a Kakao login cookie (no separate token needed). This tool obtains a valid Kakao session cookie and calls that API as-is. See API.md for the full map of reverse-engineered endpoints.

3 authentication methods (choose one)

1) macOS + Chrome auto-extraction (default)

As long as Chrome is logged in to the target channel, the session (including HttpOnly cookies) is automatically extracted from the cookie store. No extra configuration required.

node bin/kbc.js whoami   # 그냥 실행하면 됨(macOS)

2) Playwright built-in login (cross-platform · headless · recommended)

The tool logs in with its own browser and holds the session, so it works on non-macOS systems and on servers too. 2FA/captcha only needs to be handled manually once.

npm i playwright && npx playwright install chromium
node bin/kbc.js login          # 브라우저가 열림 → 카카오 로그인(2FA 포함) → 세션 저장
KBC_AUTH=playwright node bin/kbc.js whoami   # 이후 저장된 세션 사용

• The session is stored in .kbc-auth/state.json (gitignored). The daemon periodically touches the site to keep the session from expiring.

• Automatic re-login: if the session fully expires, the daemon detects it → relaunches the login browser (only 2FA is handled manually) → recovers automatically. In a headless/server environment, just run kbc login again and the new session will be picked up automatically and recovered without a restart.

3) Direct cookie injection

KBC_COOKIE="_kawlt=...; _kawltea=...; ..." node bin/kbc.js whoami

(Acquire it from your browser's DevTools → Network → copy the Cookie header of a request, or "Copy as cURL")

Requirements

• Node ≥ 20.12

• To use cookie auto-extraction: macOS + logged-in to the target Kakao Channel in Google Chrome (uses /usr/bin/sqlite3 + Keychain internally, both built into macOS)

• Other OS/browser: usable by manually injecting KBC_COOKIE

Installation

git clone <this-repo>
cd kakao-channel-chat
npm install
cp .env.example .env      # KBC_PROFILE_ID 채워넣기

.env:

KBC_PROFILE_ID=_XXXXX     # 관리자센터 URL business.kakao.com/{이값}/chats 의 {이값}
# KBC_CHROME_PROFILE=Default   # (선택) 여러 Chrome 프로필 중 지정. 미지정 시 자동탐지
# KBC_COOKIE=...               # (선택) 쿠키 자동추출 대신 직접 주입

CLI usage

node bin/kbc.js whoami                 # 로그인 상태
node bin/kbc.js token                  # 토큰 리프레시(무한로그인 확인)
node bin/kbc.js unread                 # 안읽은 방 (링크 포함)
node bin/kbc.js list --json            # 전체 방 (JSON)
node bin/kbc.js logs <chatId>          # 대화내역
node bin/kbc.js mark <chatId>          # 읽음 처리
node bin/kbc.js send <chatId> "<text>" --yes    # ⚠️ 실제 발송
node bin/kbc.js watch --poll           # 실시간 감시
node bin/kbc.js daemon                  # 상시 구동(토큰 무한유지+감시)
node bin/kbc.js daemon --autoreply      # + 안읽은 새 메시지 자동응답

Library usage

import { KakaoBizChatClient } from './src/client.js';

const c = new KakaoBizChatClient({ profileId: process.env.KBC_PROFILE_ID }); // 쿠키 자동
if ((await c.checkLogin()).loggedIn) {
  const unread = await c.getUnreadChats();               // is_read=false 방들 (+ .link)
  const { items } = await c.getChatlogs(unread[0].id);   // 대화내역 (.from = 'us'|'customer')
  await c.markRead(unread[0].id);
  // await c.sendText(unread[0].id, '답장');              // ⚠️ 실발송
}

Real-time monitoring:

import { watchPolling, watchSSE } from './src/push.js';
watchPolling(c, { onMessage: ({ chat }) => console.log('새 메시지', chat.name, chat.last_message) });

MCP server

Add to the MCP settings of Claude Code / Claude Desktop / Cursor, etc.:

{
  "mcpServers": {
    "kakao-channel": {
      "command": "node",
      "args": ["/absolute/path/to/kakao-channel-chat/src/mcp-server.js"],
      "env": {
        "KBC_PROFILE_ID": "_XXXXX",
        "KBC_CHROME_PROFILE": "Default"
      }
    }
  }
}

Exposed tools: kakao_login_status, kakao_unread_count, kakao_list_chats, kakao_get_chat, kakao_get_messages, kakao_mark_read. The sending tool (kakao_send_message) is disabled by default for safety — add KBC_MCP_ALLOW_SEND=1 to your env to expose it.

Always-on operation (PM2)

Automatically renews the token before it expires and keeps the session alive, so it never disconnects. Automatically restarts on crash:

npm i -g pm2
pm2 start ecosystem.config.cjs
pm2 logs kakao-channel
pm2 save && pm2 startup   # 부팅 시 자동 실행

With macOS cookie auto-extraction, the session is maintained indefinitely only while Chrome stays logged in (Chrome automatically renews cookies). To run fully headless without Chrome, you must periodically refresh KBC_COOKIE or implement a separate kakao SSO refresh flow.

Security / Precautions

• See SECURITY.md for the detailed security policy — what it accesses and what it does not.

• Cookies/tokens exist locally only and are never transmitted externally (communication takes place only with Kakao domains).

• Never commit .env or cookies (included in .gitignore).

• send/--autoreply are delivered immediately to real customers.

• Use only for channels you own.

License

MIT — LICENSE. Kakao and KakaoTalk are trademarks of Kakao Corp. and are not affiliated with this project.