kakao-cli

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

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

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

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

준비물

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

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

설치

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

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

https://github.com/fomula91/kakao-cli 의 README를 읽고, 설치 방법 2의 순서대로 kakao-cli를 설치한 뒤 MCP 서버로 등록해줘.

방법 2. 직접 설치하기

1단계. uv 설치

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

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

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

2단계. kakao-cli 설치

uv tool install https://github.com/fomula91/kakao-cli/archive/refs/heads/main.zip

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의 4단계와 5단계를 따라 합니다.

방법 3. 파일을 받아서 설치하기 (Claude 데스크톱 앱)

Claude Code 없이 Claude 데스크톱 앱만 쓰는 경우의 순서입니다. 받은 파일 하나로 설치합니다.

1단계. 파일 받기

아래 주소를 브라우저에서 열면 kakao-cli-main.zip 파일이 다운로드 폴더에 저장됩니다. 압축은 풀지 않습니다.

https://github.com/fomula91/kakao-cli/archive/refs/heads/main.zip

2단계. uv 설치

시작 메뉴에서 "PowerShell"을 검색해 열고, 아래 한 줄을 붙여 넣은 뒤 Enter를 누릅니다. 끝나면 PowerShell 창을 닫고 새로 엽니다.

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

3단계. 받은 파일로 설치

uv tool install "$HOME\Downloads\kakao-cli-main.zip"

파일을 다른 곳에 받았다면 따옴표 안을 그 파일의 경로로 바꿉니다. 설치가 끝나면 받은 파일은 지워도 됩니다.

카카오톡을 켜 둔 상태에서 kakao status를 실행해 로그인=True가 보이면 설치된 것입니다.

4단계. Claude 데스크톱 앱에 연결

1. PowerShell에서 아래 명령을 실행해 설치된 위치를 확인합니다. C:\Users\사용자이름\.local\bin\kakao.exe 같은 경로가 나옵니다.

   (Get-Command kakao).Source
   

2. Claude 데스크톱 앱에서 설정 → 개발자 → 구성 편집을 누릅니다. 탐색기가 열리면 claude_desktop_config.json을 메모장으로 엽니다.

3. 아래 내용을 넣고 저장합니다. command에는 1번에서 나온 경로를 넣되, \를 모두 \\로 두 번씩 씁니다.

   {
     "mcpServers": {
       "kakao": {
         "command": "C:\\Users\\사용자이름\\.local\\bin\\kakao.exe",
         "args": ["mcp"]
       }
     }
   }
   

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

4. Claude 데스크톱 앱을 완전히 종료했다가 다시 켭니다. 창만 닫으면 앱이 계속 실행 중이므로, 작업 표시줄 오른쪽 아래 트레이의 Claude 아이콘을 오른쪽 클릭해 종료합니다.

5단계. 연결 확인

새 대화에서 "카카오톡 상태 확인해줘"라고 말합니다. 처음에는 도구 사용 허용 창이 뜨고, 허용하면 로그인 상태를 알려 줍니다. 설정 → 개발자에 kakao가 실행 중으로 보이면 연결된 것입니다.

업데이트와 삭제

uv tool install --force https://github.com/fomula91/kakao-cli/archive/refs/heads/main.zip   # 최신 버전으로
uv tool install --force "$HOME\Downloads\kakao-cli-main.zip"                               # 새로 받은 파일로 최신 버전으로
uv tool uninstall ax-cartridge                                                             # 삭제
claude mcp remove kakao                                                                    # Claude Code 연결 해제

Claude 데스크톱 앱 연결을 해제하려면 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 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는 일반 채팅의 '안읽음' 폴더로 동작하고, 오픈채팅은 빠질 수 있습니다.
• 사진, 이모티콘, 파일처럼 글이 없는 메시지는 종류 표시만 나옵니다.
• 친구 목록은 넘겨 가며 읽어서 친구가 많으면 오래 걸립니다(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_send, kakao_friends, kakao_delete_friend, kakao_inspect)

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