kakao-docs-mcp

카카오 개발자(developers.kakao.com) REST API 문서를 검색하고 읽을 수 있는 검색 REST API와 MCP(Model Context Protocol) 서버입니다.

카카오는 REST API 문서를 llms.txt나 공식 MCP 형태로 제공하지 않습니다. 이 프로젝트는 그 공백을 메우는 공익 오픈소스 프로젝트입니다.

• 그냥 검색만 쓰고 싶다 → 1. 호스팅된 공개 서비스 사용하기 (설치 불필요)
• Claude에서 카카오 문서를 검색하게 하고 싶다 → 2. Claude에 MCP 연결하기
• 내 서버/로컬에서 직접 돌리고 싶다 → 3. 직접 실행 / 셀프호스트

문서 출처: 카카오 개발자 — 문서 저작권은 카카오에 있습니다. 이 프로젝트는 문서 본문을 통째로 복제·재배포하지 않습니다. 자세한 내용은 저작권 관련 설계를 참고하세요.

---

한눈에 보기

대부분의 사용자는 아무것도 설치할 필요가 없습니다. 공개 엔드포인트에서 키 1개를 발급받아 REST API와 MCP를 모두 사용합니다.

┌──────────────┐  ① POST /kakao-docs/keys (인증 불필요)
│  나 / 내 앱   │ ───────────────────────────────────→  키 발급 (kd_xxxx)
└──────┬───────┘
       │ ② Authorization: Bearer kd_xxxx
       │
       ├─────────────→  https://api.tan-kim.com/kakao-docs   (REST 검색/조회)
       │
       └─────────────→  https://mcp.tan-kim.com/kakao-docs   (Claude MCP)

용도	엔드포인트	인증
키 발급(셀프)	POST https://api.tan-kim.com/kakao-docs/keys	불필요
키워드 검색	GET https://api.tan-kim.com/kakao-docs/search?q=...	Bearer <키>
문서 본문 조회	GET https://api.tan-kim.com/kakao-docs/page/<경로>	Bearer <키>
카테고리 목록	GET https://api.tan-kim.com/kakao-docs/categories	Bearer <키>
헬스체크	GET https://api.tan-kim.com/kakao-docs/health	불필요
MCP (Claude)	https://mcp.tan-kim.com/kakao-docs	Bearer <키>

⚠️ api.tan-kim.com / mcp.tan-kim.com은 이 프로젝트의 레퍼런스 운영 도메인입니다. 직접 배포한 경우 자신의 도메인으로 바꿔 읽으세요. (아직 배포 전이라면 3. 직접 실행 또는 docs/DEPLOY.md 참고)

---

왜 이 프로젝트가 필요한가

카카오 개발자 문서는:

• llms.txt / llms-full.txt를 제공하지 않습니다 (developers.kakao.com/llms.txt → 404).
• 공식 MCP는 PlayMCP가 있지만, 이는 톡캘린더/카카오맵/기프트/멜론 등 실제 서비스 기능을 MCP 도구로 노출하는 것이지 REST API 개발 문서 자체를 위한 것이 아닙니다.

그래서 LLM/에이전트가 카카오 REST API를 정확히 참고하려면 매번 웹 검색 → 페이지 열람 → 파싱을 반복해야 합니다. 이 프로젝트는 그 과정을 검색 + 실시간 조회 툴 2개로 대체합니다.

---

1. 호스팅된 공개 서비스 사용하기

1-1. API 키 발급 (셀프 발급)

인증 없이 누구나 키를 발급받을 수 있습니다. 발급된 키 1개로 REST와 MCP를 모두 사용합니다.

curl -X POST https://api.tan-kim.com/kakao-docs/keys \
  -H "Content-Type: application/json" \
  -d '{"name":"내-에이전트"}'

응답 (원본 키는 이때 한 번만 표시됩니다 — 서버는 해시만 저장하므로 분실 시 재발급):

{
  "id": 12,
  "name": "내-에이전트",
  "rate_per_min": 30,
  "api_key": "kd_a1B2c3D4...",
  "note": "api_key는 지금만 표시됩니다. 안전한 곳에 보관하세요(서버는 해시만 저장)."
}

• 셀프 발급 키의 기본 한도는 분당 30요청입니다.
• 남용 방지를 위해 IP당 발급 횟수에 시간당 제한이 있습니다.

1-2. 키워드 검색 — GET /search

curl "https://api.tan-kim.com/kakao-docs/search?q=토큰갱신&limit=5" \
  -H "Authorization: Bearer kd_a1B2c3D4..."

쿼리 파라미터	필수	기본값	설명
q	✅	—	검색 키워드
limit	❌	5	결과 수 (최대 20)
category	❌	전체	카테고리 슬러그 필터 (예: kakaologin)

응답 (제목/카테고리/짧은 발췌만 포함 — 본문 전체는 /page로 조회):

{
  "results": [
    { "path": "kakaologin/common", "title": "카카오 로그인 > 이해하기", "category": "카카오 로그인", "snippet": "...", "score": 12.4 }
  ],
  "total": 1
}

1-3. 문서 본문 조회 — GET /page/<경로>

검색 결과의 path를 그대로 사용합니다. 본문은 매 요청마다 developers.kakao.com에서 실시간으로 가져와 마크다운으로 변환합니다(카카오 서버 부하를 줄이기 위해 최근 조회분은 짧게 캐시합니다).

curl "https://api.tan-kim.com/kakao-docs/page/kakaologin/common" \
  -H "Authorization: Bearer kd_a1B2c3D4..."

{
  "path": "kakaologin/common",
  "title": "카카오 로그인 > 이해하기",
  "sourceUrl": "https://developers.kakao.com/docs/ko/kakaologin/common",
  "markdown": "> 출처: ...\n\n# 이해하기\n\n...",
  "fetchedAt": "2026-07-17T12:00:00.000Z",
  "found": true
}

1-4. 카테고리 목록 — GET /categories

curl "https://api.tan-kim.com/kakao-docs/categories" -H "Authorization: Bearer kd_a1B2c3D4..."

---

2. Claude에 MCP 연결하기

.mcp.json 또는 Claude 설정에 발급받은 키를 넣습니다.

{
  "mcpServers": {
    "kakao-docs": {
      "type": "http",
      "url": "https://mcp.tan-kim.com/kakao-docs",
      "headers": { "Authorization": "Bearer <발급받은 API키>" }
    }
  }
}

제공 툴

툴	설명
search_kakao_docs	키워드로 카카오 REST API 문서를 검색 (제목/카테고리/짧은 발췌 반환)
get_kakao_doc_page	검색 결과의 path로 문서 본문 전체를 실시간 조회 (마크다운)
list_kakao_doc_categories	카테고리(슬러그, 한글 이름) 목록 조회

일반적인 사용 흐름: search_kakao_docs로 후보를 찾고 → get_kakao_doc_page로 필요한 문서의 본문을 읽습니다.

---

3. 직접 실행 / 셀프호스트

3-1. 로컬 개발

# 의존성 설치
npm install

# 문서 색인 (사이트맵 크롤 → 제목/헤딩/스니펫만 SQLite에 저장, 본문은 저장 안 함)
npm run index

# REST API 서버 (기본: SQLite, API 키 비활성 — 로컬 테스트용)
npm run api

# MCP 서버 (stdio, Claude Code/Desktop이 직접 프로세스로 실행)
npm run mcp

.env.example을 .env로 복사해 필요에 맞게 값을 조정합니다.

3-2. Claude Code/Desktop에 로컬 MCP 등록 (stdio)

{
  "mcpServers": {
    "kakao-docs": {
      "command": "npx",
      "args": ["tsx", "/절대경로/kakao-docs-mcp/src/mcp/server.ts"]
    }
  }
}

3-3. 운영 배포 (Docker + Oracle Cloud)

docs/DEPLOY.md를 참고하세요. API 키/사용 로그는 MySQL(RDS)에, 검색 인덱스는 서버의 SQLite 볼륨에 둡니다. namuwiki-search-mcp와 동일한 VM에 나란히 배포하도록 설계했습니다 (포트 3002/3012 사용, 3000/3001/3003/3005/3011과 충돌 없음).

---

저작권 관련 설계

카카오 개발자 문서의 저작권은 카카오에 있습니다. 이 프로젝트는 그 저작권을 존중하기 위해 다음과 같이 설계했습니다.

• 검색 인덱스에는 본문 전체를 저장하지 않습니다. 제목/헤딩/200자 이내 발췌만 SQLite에 색인합니다.
• 본문은 항상 실시간 조회입니다. get_kakao_doc_page / GET /page/* 호출 시마다 developers.kakao.com에서 그때그때 가져와 반환하며, 디스크에 영속 저장하지 않습니다 (반복 요청 부하 완화를 위한 짧은 인메모리 캐시만 사용, 기본 15분).
• 응답에는 항상 출처 URL과 저작권 고지를 포함합니다.
• 크롤러는 robots.txt를 준수하고(/docs/ko/*는 허용됨), 식별 가능한 User-Agent와 요청 간 지연을 사용해 카카오 서버에 부담을 주지 않습니다.

---

라이선스

이 저장소의 코드는 MIT License로 배포됩니다. 카카오 문서 콘텐츠 자체는 카카오의 저작물이며 이 라이선스의 대상이 아닙니다.