Metadata-Version: 2.3
Name: ax-cartridge
Version: 0.1.3
Summary: AX카트리지: 카카오톡 PC 앱을 조작하는 CLI와 MCP 서버 (Windows, macOS)
Requires-Dist: mcp>=2.3.0
Requires-Dist: pyobjc-framework-applicationservices>=13.0 ; sys_platform == 'darwin'
Requires-Dist: pyobjc-framework-cocoa>=13.0 ; sys_platform == 'darwin'
Requires-Dist: uiautomation>=2.0.29 ; sys_platform == 'win32'
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# 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
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

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

**2단계. kakao-cli 설치**

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

```powershell
uv tool install ax-cartridge
```

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

**3단계. 동작 확인**

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

```powershell
kakao status
```

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

**4단계. Claude에 연결**

Claude Code를 쓰는 경우:

```powershell
claude mcp add --scope user kakao -- kakao mcp
```

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

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

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

**1단계. uv 설치**

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

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

**2단계. 설정 파일에 추가**

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

```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"`에 넣습니다(`\`는 `\`로 두 번씩 씁니다).

### 업데이트와 삭제

```powershell
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 기반이 아닌 버전)은 지원하지 않습니다.

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

```powershell
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`만 작성되어 있고 실행해 보지 못했습니다.

## 개발자용

```powershell
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`을 올려 커밋한 뒤 같은 번호로 태그를 답니다.

```powershell
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`를 고칩니다.
