# kakao-mcp

카카오 API를 AI 에이전트에 연결하는 MCP 서버. **지도/로컬, 다음 검색, 비전 OCR**을 REST API 키 하나로 바로 사용.

Kakao's Local (Map), Search, and Vision APIs as a Model Context Protocol server — Korea's location & content stack for Claude, Cursor, and any MCP client.

## 왜?

한국 앱·마케팅 개발에서 매일 필요한데(주소→좌표, 주변 장소, 국내 검색, 이미지 OCR) 깔끔한 MCP가 없었어요. 유저 OAuth 없이 **REST 키 하나로 즉시** 돌아갑니다.

## 설치

```bash
npx kakao-mcp
```

REST API 키는 [developers.kakao.com](https://developers.kakao.com) → 내 애플리케이션 → 앱 키 → **REST API 키**.

### Claude Code / Claude Desktop

`claude_desktop_config.json` (또는 `.mcp.json`):

```json
{
  "mcpServers": {
    "kakao": {
      "command": "npx",
      "args": ["-y", "kakao-mcp"],
      "env": { "KAKAO_REST_API_KEY": "your_rest_api_key" }
    }
  }
}
```

## 툴 (v0.1 · T1)

| 툴 | 설명 |
|---|---|
| `kakao_address_to_coord` | 주소 → 위경도 좌표 + 정규화 주소 |
| `kakao_search_place` | 키워드 장소 검색 (좌표+반경 주변검색 지원) |
| `kakao_place_by_category` | 카테고리별 주변 장소 (카페·음식점·병원 등) |
| `kakao_coord_to_address` | 좌표 → 도로명/지번 주소 |
| `kakao_coord_to_region` | 좌표 → 행정동/법정동 |
| `kakao_search` | 다음 검색: 웹/블로그/카페/이미지/동영상/책 |
| `kakao_ocr` | 이미지 URL에서 텍스트 추출 (OCR) |

### 써보기

> "판교역로 235 좌표 알려줘"
> "강남역 반경 500m 카페 5개 찾아줘"
> "이 좌표(127.02, 37.5) 무슨 동이야?"
> "블로그에서 '분당 브런치' 검색해줘"

## 로드맵

- **v0.2 (T2)** — 카카오 로그인(OAuth) · 나에게 메시지 보내기(알림 훅)
- **v0.3 (T3)** — 카카오톡 채널 · 알림톡/친구톡 · 카카오모먼트 광고

## 개발

```bash
npm install
npm run build
KAKAO_REST_API_KEY=... npm start
```

## 라이선스

MIT © Kioko Lab