카카오 로컬 API MCP 연동 — 주소 검색·카테고리 장소 조회 자동화 가이드
카카오 로컬 API를 MCP로 연동해 Claude에서 주소 검색, 카테고리 장소 조회를 자동화하는 방법을 단계별로 설명합니다. API 키 발급부터 설정 완료까지 한 번에.
카카오 로컬 API를 MCP로 연동하면 Claude 대화 창에서 주소 검색, 카테고리별 장소 조회, 키워드 검색을 별도 코드 없이 즉시 실행할 수 있습니다. REST API 키 하나만 준비하면 되며, Claude Desktop·Claude Code 모두 지원됩니다. 이 글은 API 키 발급부터 MCP 서버 구성, Claude 연결, 오류 해결까지 전 과정을 단계별로 다룹니다.
카카오 로컬 API란 무엇이고 왜 MCP로 연결하는가
카카오 로컬 API는 카카오가 제공하는 장소·주소 데이터 조회 REST API입니다. 키워드로 장소를 검색하거나, 카테고리(카페·병원·편의점 등)로 반경 내 장소를 필터링하거나, 도로명·지번 주소를 위도·경도 좌표로 변환할 수 있습니다. 국내 POI(관심 지점) 데이터베이스로는 가장 포괄적인 축에 속해 배달 플랫폼, 부동산 앱, 물류 시스템 등 다양한 서비스에서 활용됩니다.
그런데 Claude는 기본적으로 외부 API 호출 능력이 없습니다. 사용자가 “마포구 카페 리스트 뽑아줘”라고 요청해도 Claude는 실시간 데이터를 가져오지 못합니다. MCP(Model Context Protocol)는 이 문제를 해결하는 표준 인터페이스입니다. 카카오 로컬 API를 MCP 도구로 래핑해 Claude에 연결하면, 자연어 요청이 실시간 API 호출로 자동 변환되어 결과가 돌아옵니다.
카카오맵 MCP와 카카오 로컬 API MCP의 차이
카카오맵 MCP와 카카오 로컬 API MCP는 혼동하기 쉽지만 목적이 다릅니다.
| 구분 | 카카오맵 MCP | 카카오 로컬 API MCP |
|---|---|---|
| 주요 목적 | 지도 시각화, 경로 안내 | 장소 데이터 수집·검색·자동화 |
| 활용 시나리오 | ”지도에서 경로 보여줘" | "주변 약국 목록을 JSON으로 뽑아줘” |
| API 엔드포인트 | Maps SDK, 길찾기 API | /v2/local/search/*, /v2/local/geo/* |
| 결과 형태 | 지도 렌더링 중심 | 구조화 데이터(JSON) 중심 |
데이터 파이프라인, 자동화 스크립트, 장소 분석 등에는 카카오 로컬 API MCP가 더 적합합니다.
카카오 로컬 API 주요 엔드포인트
MCP 서버가 래핑할 API 엔드포인트를 미리 파악해 두면 도구 설계와 디버깅이 훨씬 쉬워집니다.
| 기능 | 엔드포인트 | 주요 파라미터 |
|---|---|---|
| 키워드 장소 검색 | /v2/local/search/keyword.json | query, x, y, radius, page |
| 카테고리 장소 검색 | /v2/local/search/category.json | category_group_code, x, y, radius |
| 주소 검색(지오코딩) | /v2/local/search/address.json | query, page |
| 좌표 → 주소 변환 | /v2/local/geo/coord2address.json | x, y |
| 좌표계 변환 | /v2/local/geo/transcoord.json | x, y, input_coord, output_coord |
모든 엔드포인트는 https://dapi.kakao.com 베이스 URL을 사용하고, 요청 헤더에 Authorization: KakaoAK {REST_API_KEY}를 포함해야 합니다.
데이터 흐름 한눈에 보기
사용자 자연어 요청
↓
Claude (LLM) — 의도 파악 및 도구 선택
↓
카카오 로컬 API MCP 서버 — API 파라미터 조립
↓
https://dapi.kakao.com/v2/local/... — 실제 API 호출
↓
JSON 응답 → MCP 서버 → Claude — 자연어로 정리해 사용자에게 전달MCP 서버는 Claude와 카카오 API 사이의 번역 계층입니다. Claude가 “강남구 반경 1km 편의점 찾아줘”라고 판단하면, MCP 서버는 카테고리 코드 CS2, x·y 좌표, radius=1000 파라미터를 조합해 API를 호출하고 결과를 구조화해 돌려줍니다.
준비물
- 카카오 개발자 계정 및 REST API 키
- Node.js 18 이상 또는 Python 3.10 이상(사용할 MCP 서버 구현체에 따라 다름)
- Claude Desktop 최신 버전 또는 Claude Code CLI
단계별 연동 방법
1단계 — 카카오 개발자 앱 생성 및 REST API 키 발급
카카오 개발자 콘솔에 접속해 로그인합니다. 상단 내 애플리케이션 메뉴에서 애플리케이션 추가하기를 클릭하고 앱 이름을 입력합니다(예: kakao-local-mcp).
앱이 생성되면 왼쪽 메뉴에서 앱 키 탭을 선택합니다. 여기서 REST API 키를 확인하고 복사해 둡니다. JavaScript 키나 Admin 키가 아닌 REST API 키여야 합니다.
로컬 개발 환경에서 테스트할 경우 플랫폼 메뉴 > Web 플랫폼 등록 > 사이트 도메인에 http://localhost를 추가하면 도메인 검증 오류를 예방할 수 있습니다.
2단계 — MCP 서버 구현 선택
카카오 로컬 API를 MCP로 래핑하는 방법은 크게 두 가지입니다.
방법 A: 직접 MCP 서버 구현 (Python FastMCP 예시)
카카오 로컬 API를 직접 MCP 도구로 만들고 싶다면 Python의 mcp 라이브러리를 활용할 수 있습니다. 아래는 키워드 검색 도구를 등록하는 최소 구조입니다.
# Python 환경 준비
python3 -m venv .venv
source .venv/bin/activate
pip install mcp httpx# kakao_local_mcp.py
import os
import httpx
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("kakao-local")
KAKAO_API_KEY = os.environ.get("KAKAO_REST_API_KEY", "")
BASE_URL = "https://dapi.kakao.com/v2/local"
@mcp.tool()
async def search_keyword(query: str, x: str = "", y: str = "", radius: int = 0, page: int = 1) -> dict:
"""카카오 로컬 키워드 장소 검색"""
headers = {"Authorization": f"KakaoAK {KAKAO_API_KEY}"}
params = {"query": query, "page": page}
if x and y:
params.update({"x": x, "y": y, "radius": radius})
async with httpx.AsyncClient() as client:
resp = await client.get(f"{BASE_URL}/search/keyword.json", headers=headers, params=params)
return resp.json()
@mcp.tool()
async def search_category(category_group_code: str, x: str, y: str, radius: int = 1000) -> dict:
"""카카오 로컬 카테고리 장소 검색 (예: CE7=카페, FD6=음식점, PM9=약국)"""
headers = {"Authorization": f"KakaoAK {KAKAO_API_KEY}"}
params = {"category_group_code": category_group_code, "x": x, "y": y, "radius": radius}
async with httpx.AsyncClient() as client:
resp = await client.get(f"{BASE_URL}/search/category.json", headers=headers, params=params)
return resp.json()
@mcp.tool()
async def search_address(query: str, page: int = 1) -> dict:
"""카카오 로컬 주소 검색 — 도로명·지번 주소를 좌표로 변환"""
headers = {"Authorization": f"KakaoAK {KAKAO_API_KEY}"}
async with httpx.AsyncClient() as client:
resp = await client.get(f"{BASE_URL}/search/address.json", headers=headers, params={"query": query, "page": page})
return resp.json()
if __name__ == "__main__":
mcp.run()방법 B: 기존 한국 API MCP 서버 활용
카카오 로컬 API를 포함하는 한국 통합 MCP 서버를 찾고 있다면 MCP모아 카카오·네이버 카테고리를 확인하세요. 개발자 커뮤니티에서 공개된 구현체를 찾을 수 있습니다.
3단계 — Claude Desktop 설정 파일에 MCP 서버 등록
Claude Desktop 설정 파일 경로는 운영체제별로 다릅니다.
| 운영체제 | 설정 파일 경로 |
|---|---|
| macOS | ~/Library/Application Support/Claude/claude_desktop_config.json |
| Windows | %APPDATA%\Claude\claude_desktop_config.json |
Python으로 구현한 경우 설정 파일에 다음을 추가합니다.
{
"mcpServers": {
"kakao-local": {
"command": "/절대경로/.venv/bin/python",
"args": ["/절대경로/kakao_local_mcp.py"],
"env": {
"KAKAO_REST_API_KEY": "발급받은_REST_API_키_입력"
}
}
}
}/절대경로/ 부분은 실제 파일이 있는 디렉터리의 절대 경로로 바꾸세요. macOS 기준으로 ~ 대신 /Users/사용자명/ 형식을 사용해야 합니다.
4단계 — Claude Code(CLI) 사용자 설정
Claude Code를 쓴다면 프로젝트 루트의 .claude/settings.json에 동일한 형식으로 추가합니다.
{
"mcpServers": {
"kakao-local": {
"command": "/절대경로/.venv/bin/python",
"args": ["/절대경로/kakao_local_mcp.py"],
"env": {
"KAKAO_REST_API_KEY": "발급받은_REST_API_키_입력"
}
}
}
}5단계 — 동작 검증
Claude Desktop을 완전히 종료한 뒤 다시 실행합니다. 새 대화에서 아래 프롬프트로 테스트하세요.
카카오 로컬 API로 서울 강남구 테헤란로 152 주소를 좌표로 변환해줘.또는 카테고리 검색을 테스트하려면 좌표를 먼저 알아야 합니다.
카카오 로컬 API로 강남역(위도 37.4979, 경도 127.0276) 반경 500m 카페를 검색해줘.Claude가 MCP 도구를 호출해 장소 이름, 주소, 전화번호, 카카오맵 링크가 포함된 결과를 반환하면 연결 성공입니다.
주요 카테고리 코드 참고표
카테고리 검색 도구 호출 시 category_group_code 값이 필요합니다.
| 코드 | 카테고리 | 코드 | 카테고리 |
|---|---|---|---|
| MT1 | 대형마트 | CS2 | 편의점 |
| PS3 | 어린이집·유치원 | SC4 | 학교 |
| AC5 | 학원 | PK6 | 주차장 |
| OL7 | 주유소·충전소 | SW8 | 지하철역 |
| BK9 | 은행 | CT1 | 문화시설 |
| AG2 | 중개업소 | PO3 | 공공기관 |
| AT4 | 관광명소 | AD5 | 숙박 |
| FD6 | 음식점 | CE7 | 카페 |
| HP8 | 병원 | PM9 | 약국 |
전체 코드 목록은 카카오 개발자 문서의 카테고리 검색 항목에서 확인할 수 있습니다.
흔한 오류와 해결 방법
401 Unauthorized — KakaoAK 인증 실패
{"errorType":"AuthorizationException","message":"..."}REST API 키가 아닌 다른 키를 사용했거나, 환경 변수가 제대로 전달되지 않은 경우입니다. 아래를 확인하세요.
- 카카오 개발자 콘솔 > 앱 > 앱 키 탭에서 REST API 키 확인
claude_desktop_config.json의env블록에 키가 올바르게 입력됐는지 확인- 키 앞뒤에 공백이 없는지 확인
허가되지 않은 도메인 오류
일부 엔드포인트는 Web 플랫폼 등록이 필요합니다. 카카오 개발자 콘솔 > 앱 > 플랫폼 > Web에 http://localhost를 등록하세요.
MCP 서버가 Claude에 보이지 않음
설정 파일의 JSON 문법 오류나 경로 문제가 대부분입니다. 아래 명령으로 JSON 유효성을 확인하세요.
# macOS 기준 — 문법 오류가 있으면 오류 메시지 출력
python3 -m json.tool ~/Library/Application\ Support/Claude/claude_desktop_config.json정상이면 JSON이 그대로 출력됩니다. 이상이 없는데도 안 보인다면 Python 실행 파일 경로가 절대 경로인지 다시 확인하세요.
Python 모듈 없음 오류
ModuleNotFoundError: No module named 'mcp'가상환경이 활성화되지 않았거나, command 경로가 시스템 Python을 가리키는 경우입니다. command 값을 가상환경 내 Python 절대 경로(예: /Users/사용자명/프로젝트/.venv/bin/python)로 지정하세요.
검색 결과 없음
- 키워드가 너무 짧거나 모호한 경우: “카페” 대신 “스타벅스 강남역”처럼 구체적으로 입력
- 반경이 너무 좁은 경우: radius를 1000(1km) 이상으로 늘려보세요
- 카테고리 코드 오류: 위 참고표에서 정확한 코드를 확인하세요
실용 활용 예시
카카오 로컬 API MCP를 Claude와 조합하면 다양한 자동화가 가능합니다.
| 시나리오 | 카카오 로컬 API 활용 |
|---|---|
| 상권 분석 보고서 | 특정 좌표 반경 내 업종별 장소 수 집계 |
| 물류 최적화 | 주소 목록을 좌표로 일괄 변환해 거리 계산 |
| 부동산 입지 분석 | 학교·지하철·편의점 근접성 자동 조회 |
| 고객 DB 정제 | 입력된 주소를 정규화된 도로명 주소로 변환 |
| 마케팅 타깃팅 | 매장 주변 경쟁 업체 리스트 자동 수집 |
Claude에게 “서울 강남구에 있는 모든 약국 목록을 엑셀에 정리해줘”라고 요청하면, MCP를 통해 카카오 로컬 API를 페이지별로 순회하며 데이터를 수집하고 표로 정리해 줄 수 있습니다.
함께 쓰면 좋은 한국 MCP 서버
카카오 로컬 API MCP와 함께 사용하면 시너지가 높은 MCP 서버를 소개합니다.
- 한국어 맞춤법 검사 MCP — 장소 검색 결과를 포함한 보고서 작성 시 맞춤법을 자동으로 교정합니다.
- 네이웍스 MCP 서버 — 수집한 장소 데이터를 LINE WORKS 메시지·캘린더·드라이브에 자동으로 공유할 수 있습니다.
- 에이전트웹서치 MCP — 카카오 로컬로 찾은 장소의 최신 리뷰나 영업 정보를 네이버·구글 검색으로 보완할 수 있습니다.
더 많은 한국 MCP 서버는 카카오·네이버 카테고리와 전체 서버 목록에서 확인하세요.
자주 묻는 질문
카카오 로컬 API MCP와 카카오맵 MCP는 어떻게 다른가요?
카카오맵 MCP는 지도 시각화·길찾기에 초점을 맞춘 반면, 카카오 로컬 API MCP는 주소 검색(지오코딩), 카테고리 장소 조회, 키워드 검색 등 데이터 수집·자동화 목적에 특화됩니다. 지도를 보여줄 필요 없이 장소 데이터를 프로그래밍 방식으로 처리할 때 카카오 로컬 API가 더 적합합니다.
카카오 로컬 API는 무료로 사용할 수 있나요?
카카오 로컬 API는 카카오 개발자 계정만 있으면 무료로 사용할 수 있습니다. 카카오 공식 문서에 따르면 일반 앱 기준으로 사용량 제한이 있으므로, 대량 호출이 필요하다면 카카오 developers 페이지의 할당량 정책을 확인하세요.
REST API 키 외에 다른 키가 필요한가요?
카카오 로컬 API는 REST API 키만 있으면 됩니다. JavaScript 키, Admin 키, Native 앱 키는 필요하지 않습니다. 요청 헤더에 Authorization: KakaoAK {REST_API_KEY} 형식으로 인증합니다.
카테고리 코드는 어디서 확인하나요?
카카오 로컬 API 공식 문서(developers.kakao.com)의 ‘카테고리 검색’ 항목에서 MT1(대형마트), CS2(편의점), PM9(약국), CE7(카페), FD6(음식점) 등 전체 카테고리 코드 목록을 확인할 수 있습니다. 이 가이드 상단의 참고표도 활용하세요.
주소 검색(지오코딩) 결과가 없으면 어떻게 하나요?
입력 주소가 너무 짧거나 행정구역이 불분명하면 결과가 없을 수 있습니다. ‘서울특별시 강남구 테헤란로 152’처럼 시·구·도로명까지 상세하게 입력하세요. 도로명 주소와 지번 주소 모두 지원합니다.
Claude Code(CLI)에서도 카카오 로컬 API MCP를 쓸 수 있나요?
네. Claude Code는 프로젝트 루트의 .claude/settings.json 또는 글로벌 설정 파일의 mcpServers 항목에 동일한 형식으로 등록하면 됩니다. Claude Desktop 설정과 JSON 구조가 동일합니다.
다음 단계
카카오 로컬 API MCP를 Claude에 연결했다면 상권 분석, 주소 정제, 장소 데이터 파이프라인 등 다양한 자동화 워크플로를 바로 시작할 수 있습니다. Claude에게 반복 작업을 자연어로 지시하고, MCP가 실제 API 호출을 대신 처리하는 구조는 생산성을 크게 높여줍니다.
다른 한국 MCP 서버가 궁금하다면 MCP모아 가이드 목록을 둘러보세요. 카카오 로컬 API를 활용한 MCP 서버를 직접 만들었다면 서버 등록을 통해 공유해 주세요.