kakao-cli

Claude가 내 PC의 카카오톡을 읽고 쓸 수 있게 해주는 도구입니다. 설치하면 Claude에게 이렇게 말할 수 있습니다.

• "안 읽은 카카오톡 채팅방 알려줘"
• "○○ 채팅방 최근 대화 100개 읽고 요약해줘"
• "○○ 채팅방 10월 대화 요약해줘", "○○ 채팅방 전체를 월별로 정리해줘"
• "나와의 채팅에 오늘 할 일 정리해서 보내줘"

내 PC에 설치된 카카오톡 앱 화면을 그대로 다루는 방식이라 카카오 계정 정보나 API 키가 필요 없고, 대화 내용이 이 도구를 통해 다른 서버로 나가지 않습니다. (Claude에게 읽어 달라고 한 내용은 Claude에게 전달됩니다.)

카카오톡 창을 앞으로 가져오지 않아서, 다른 창에서 작업하는 동안 실행해도 키보드 입력과 마우스가 그대로입니다.

준비물

• Windows 10 또는 11
• 카카오톡 PC 버전 (로그인된 상태, 메인 창은 열어 두기. 최소화는 괜찮음)
• Claude Code 또는 Claude 데스크톱 앱

macOS는 아직 지원하지 않습니다.

설치

방법 1. Claude에게 맡기기 (가장 쉬움)

Claude Code를 열고 아래 문장을 그대로 붙여 넣습니다.

uv가 없으면 설치하고, uv tool install ax-cartridge 로 설치한 다음, claude mcp add --scope user kakao -- kakao mcp 로 MCP 서버를 등록해줘.

방법 2. 직접 설치하기

1단계. uv 설치

시작 메뉴에서 "PowerShell"을 검색해 열고, 아래 한 줄을 붙여 넣은 뒤 Enter를 누릅니다.

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

끝나면 PowerShell 창을 닫고 새로 엽니다.

2단계. kakao-cli 설치

PyPI에 ax-cartridge라는 이름으로 올라가 있습니다. 설치되는 명령은 kakao입니다.

uv tool install ax-cartridge

Python이 없어도 uv가 알아서 받아 줍니다.

3단계. 동작 확인

카카오톡을 켜 둔 상태에서 실행합니다.

kakao status

로그인=True가 보이면 성공입니다. kakao 명령을 찾을 수 없다고 나오면 uv tool update-shell을 실행하고 PowerShell을 새로 엽니다.

4단계. Claude에 연결

Claude Code를 쓰는 경우:

claude mcp add --scope user kakao -- kakao mcp

Claude 데스크톱 앱을 쓰는 경우: 아래 "방법 3"을 따라 합니다.

방법 3. Claude 데스크톱 앱에 설치하기

kakao-cli를 따로 설치하지 않습니다. 설정 파일에 적어 두면 앱이 켜질 때 PyPI에서 받아 실행합니다.

1단계. uv 설치

시작 메뉴에서 "PowerShell"을 검색해 열고, 아래 한 줄을 붙여 넣은 뒤 Enter를 누릅니다. 이미 uv가 있으면 건너뜁니다.

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

2단계. 설정 파일에 추가

Claude 데스크톱 앱에서 설정 → 개발자 → 구성 편집을 누릅니다. 탐색기가 열리면 claude_desktop_config.json을 메모장으로 열어 아래 내용을 넣고 저장합니다. 고칠 곳 없이 그대로 붙여 넣으면 됩니다.

{
  "mcpServers": {
    "kakao": {
      "command": "uvx",
      "args": ["--from", "ax-cartridge", "kakao", "mcp"]
    }
  }
}

이미 다른 내용이 있는 파일이라면 "mcpServers" 안에 "kakao": { ... } 부분만 추가합니다.

3단계. 앱 다시 켜기

Claude 데스크톱 앱을 완전히 종료했다가 다시 켭니다. 창만 닫으면 앱이 계속 실행 중이므로, 작업 표시줄 오른쪽 아래 트레이의 Claude 아이콘을 오른쪽 클릭해 종료합니다. 처음 켤 때는 내려받느라 몇 초 걸립니다.

4단계. 확인

카카오톡을 켜 둔 상태에서 새 대화에 "카카오톡 상태 확인해줘"라고 말합니다. 처음에는 도구 사용 허용 창이 뜨고, 허용하면 로그인 상태를 알려 줍니다.

도구가 보이지 않으면 설정 → 개발자에서 kakao의 상태와 오류 내용을 확인합니다. uvx를 찾을 수 없다고 나오면 PowerShell에서 (Get-Command uvx).Source로 나온 경로를 "command"에 넣습니다(\는 \로 두 번씩 씁니다).

업데이트와 삭제

uv tool upgrade ax-cartridge     # 최신 버전으로
uv tool uninstall ax-cartridge   # 삭제
claude mcp remove kakao          # Claude Code 연결 해제

Claude 데스크톱 앱(방법 3)은 uv cache clean ax-cartridge를 실행하고 앱을 다시 켜면 최신 버전을 받습니다. 연결을 해제하려면 claude_desktop_config.json에서 "kakao": { ... } 부분을 지우고 앱을 다시 켭니다.

사용하면서 알아둘 점

• 채팅방 이름은 정확히 말해야 합니다. 이름이 조금이라도 다르거나 같은 이름이 여러 개면 보내지 않고 후보를 보여줍니다.
• 보내기 전에 한 번 확인합니다. Claude는 먼저 시험 실행(드라이런)을 하고, 실제 전송은 따로 요청해야 합니다.
• 읽으면 읽음 처리됩니다. 채팅방을 실제로 여는 방식이라 상대방에게 보이는 숫자(1)가 사라집니다.
• 채팅방 창이 잠깐 떴다 사라집니다. 포커스는 가져가지 않지만 화면에는 보입니다.
• 카카오톡을 완전히 닫아 두면 처음 실행할 때 카카오톡이 켜지면서 한 번 앞으로 나옵니다.
• 입력창에 쓰던 글이 있으면 덮어쓰지 않고 멈춥니다.
• 친구 삭제는 되돌릴 수 없습니다. 이름이 정확히 일치하는 친구가 한 명일 때만 삭제하고, Claude는 먼저 시험 실행(드라이런)을 합니다.

문제 해결

증상	해결
카카오톡에 로그인되어 있지 않습니다	카카오톡에 로그인한 뒤 다시 시도
카카오톡 실행 파일을 찾지 못했습니다	카카오톡을 기본 위치가 아닌 곳에 설치한 경우. 환경 변수 KAKAOTALK_EXE에 KakaoTalkUI.exe 전체 경로를 지정
채팅방을 못 찾음	kakao chats --query 이름으로 정확한 이름을 확인
카카오톡 업데이트 뒤 갑자기 안 됨	카카오톡 화면 구조가 바뀐 경우. 저장소에 이슈로 알려주세요
Claude에 도구가 안 보임	Claude를 완전히 종료했다가 다시 실행. Claude Code는 claude mcp list로 등록 여부 확인

카카오톡 26.9.2에서 확인했습니다. 이전의 구버전 카카오톡(Qt 기반이 아닌 버전)은 지원하지 않습니다.

명령어 (터미널에서 직접 쓸 때)

kakao status                            # 실행·로그인 상태
kakao chats --limit 30                  # 채팅방 목록 (일반 + 오픈채팅)
kakao chats --query 홍길동              # 이름으로 찾기
kakao chats --unread                    # 안 읽은 채팅방
kakao read "채팅방 이름" --limit 50     # 최근 메시지 읽기
kakao read "채팅방 이름" --since 2026-10-01 --until 2026-10-31   # 기간으로 읽기
kakao send "채팅방 이름" "메시지" --dry-run   # 보낼 수 있는지만 확인
kakao send "채팅방 이름" "메시지"       # 실제 전송
kakao friends --limit 100               # 친구 목록
kakao friends --query 홍길동            # 이름으로 친구 찾기
kakao delete-friend "친구 이름" --dry-run     # 삭제할 수 있는지만 확인
kakao delete-friend "친구 이름"         # 실제 삭제 (되돌릴 수 없음)

kakao --json chats처럼 --json을 앞에 붙이면 JSON으로 출력합니다.

알려진 한계

• 안 읽은 메시지 수는 형식을 확인하지 못했습니다. --unread는 일반 채팅의 '안읽음' 폴더로 동작하고, 오픈채팅은 빠질 수 있습니다.
• 사진, 이모티콘, 파일처럼 글이 없는 메시지는 종류 표시만 나옵니다.
• 대화는 최신 메시지부터 거꾸로 넘기며 읽어서 오래된 기간일수록 오래 걸립니다(400개에 1분 20초쯤). 기간으로 읽을 때는 3,000개까지 넘겨 읽고, 거기서 멈추면 알려 줍니다.
• 친구 목록은 넘겨 가며 읽어서 친구가 많으면 오래 걸립니다(4,000명에 10분쯤). 이름과 상태메시지가 모두 같은 친구는 한 명으로 나옵니다.
• 이름이 같은 친구가 여러 명이면 누구인지 가릴 수 없어 삭제하지 않습니다.
• macOS는 status와 inspect만 작성되어 있고 실행해 보지 못했습니다.

개발자용

git clone https://github.com/fomula91/kakao-cli
cd kakao-cli
uv sync
uv run kakao status
uv run kakao inspect --mask     # 카카오톡 UI 트리 덤프 (글자 가림)

PyPI 배포는 태그를 푸시하면 GitHub Actions(.github/workflows/publish.yml)가 합니다. pyproject.toml의 version을 올려 커밋한 뒤 같은 번호로 태그를 답니다.

git tag v0.1.1
git push origin main v0.1.1

src/kakao_cli/
  core.py        모델, 오류, 채팅방 매칭 규칙, 플랫폼별 백엔드 선택
  windows.py     Windows 백엔드
  macos.py       macOS 백엔드 (status, inspect)
  cli.py         kakao 명령
  mcp_server.py  MCP 도구 (kakao_status, kakao_chats, kakao_read, kakao_history, kakao_send, kakao_friends, kakao_delete_friend, kakao_inspect)

Windows 백엔드는 읽기에 UI Automation을, 클릭과 휠에 창 메시지 전달(PostMessage)을, 글자 입력에 MSAA 값 설정을 씁니다. UI Automation의 Invoke/Select/SetValue는 카카오톡 창을 앞으로 가져오기 때문에 쓰지 않습니다. 카카오톡 UI가 바뀌면 kakao inspect로 구조를 확인해 windows.py를 고칩니다.