kakao-channel-chat

비공식(Unofficial). 카카오 채널 관리자센터(비즈니스 채팅, 내부 코드명 "rocket")의 문서화되지 않은 내부 API를 리버스 엔지니어링한 것입니다. 카카오의 공식 제품이 아니며, 스펙이 예고 없이 바뀌어 깨질 수 있고 카카오 이용약관에 저촉될 수 있습니다. 본인 소유 채널의 자동화 용도로, 책임 하에 사용하세요. 자세한 건 DISCLAIMER.

로그인된 브라우저 세션을 그대로 재사용해 카카오 채널 채팅을 코드로 다루는 Node 툴킷. API 라이브러리 · CLI · MCP 서버 세 가지 형태로 제공합니다. 외부 런타임 의존성은 MCP SDK 하나뿐(라이브러리/CLI는 의존성 0).

되는 것

• ✅ 로그인 상태 확인 & 토큰 무한 리프레시 (세션 안 끊김)

• ✅ 채팅방 리스트 + 읽음/안읽음 구분 + 방 딥링크

• ✅ 대화내역 조회 (우리/고객/시스템 메시지 구분, 링크 추출)

• ✅ 읽음 처리, 메시지 전송(답장)

• ✅ 실시간 신규 메시지 감시 (SSE / 폴링)

• ✅ 상시 데몬 (토큰 자동갱신 + keepalive + 감시 + 선택적 자동응답)

• ✅ MCP 서버 — Claude/Cursor 등에서 툴로 사용

Related MCP server: @chatmaid/mcp

동작 원리

카카오 채널 채팅 API(business.kakao.com/api/*)는 kakao 로그인 쿠키만으로 인증됩니다(별도 토큰 불필요). 이 툴은 유효한 kakao 세션 쿠키를 확보해 그 API를 그대로 호출합니다. 리버스한 엔드포인트 전체 맵은 API.md 참고.

인증 방식 3가지 (하나 선택)

1) macOS + Chrome 자동추출 (기본) Chrome에 대상 채널로 로그인만 돼 있으면, 쿠키 저장소에서 세션을 자동 추출(HttpOnly 포함). 별도 설정 불필요.

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

2) Playwright 자체 로그인 (크로스플랫폼 · 헤드리스 · 권장) 도구가 자체 브라우저로 로그인하고 세션을 보유 → macOS가 아니어도, 서버에서도 동작. 2FA/캡차는 최초 1회만 직접 처리.

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

• 세션은 .kbc-auth/state.json(gitignore)에 저장. daemon이 주기적으로 사이트를 터치해 세션을 안 풀리게 유지.

• 자동 재로그인: 세션이 완전히 풀리면 데몬이 감지 → 로그인 브라우저를 다시 띄움(2FA만 직접 처리) → 자동 복구. 헤드리스/서버면 kbc login을 다시 실행하면 데몬이 새 세션을 자동으로 주워 재시작 없이 복구.

3) 쿠키 직접 주입

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

(브라우저 DevTools → Network → 요청의 Cookie 헤더 복사, 또는 "Copy as cURL")

요구사항

• Node ≥ 20.12

• 쿠키 자동추출을 쓰려면: macOS + Google Chrome에 대상 카카오 채널 로그인 상태 (내부적으로 /usr/bin/sqlite3 + Keychain 사용, macOS 기본 탑재)

• 다른 OS/브라우저: KBC_COOKIE 수동 주입으로 사용 가능

설치

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 사용법

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      # + 안읽은 새 메시지 자동응답

라이브러리 사용

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, '답장');              // ⚠️ 실발송
}

실시간 감시:

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

MCP 서버

Claude Code / Claude Desktop / Cursor 등의 MCP 설정에 추가:

{
  "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"
      }
    }
  }
}

노출 툴: kakao_login_status, kakao_unread_count, kakao_list_chats, kakao_get_chat, kakao_get_messages, kakao_mark_read. 발송 툴(kakao_send_message)은 안전상 기본 비활성 — KBC_MCP_ALLOW_SEND=1 을 env에 추가하면 노출됩니다.

상시 구동 (PM2)

토큰을 만료 전 자동 갱신하고 세션을 살려둬 끊기지 않게 돌립니다. 크래시 시 자동 재시작:

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

macOS 쿠키 자동추출 방식은 Chrome이 로그인 상태로 유지돼야 세션이 무한 유지됩니다(Chrome이 쿠키를 자동 갱신). Chrome 없이 완전 헤드리스로 돌리려면 KBC_COOKIE 를 주기적으로 갱신하거나 kakao SSO refresh 흐름을 별도 구현해야 합니다.

보안 / 주의

• 상세 보안 정책은 SECURITY.md — 무엇에 접근하고 무엇을 안 하는지 명시.

• 쿠키·토큰은 로컬에만 존재하며 외부로 전송하지 않습니다(통신은 카카오 도메인만).

• .env 와 쿠키는 절대 커밋하지 마세요(.gitignore에 포함됨).

• send/--autoreply 는 실제 고객에게 즉시 전달됩니다.

• 본인 소유 채널에만 사용하세요.

라이선스

MIT — LICENSE. 카카오/KakaoTalk 은 Kakao Corp.의 상표이며 본 프로젝트와 무관합니다.