카카오맵 MCP를 Claude에 연결하기 — 장소 검색부터 주소·좌표 변환까지

카카오맵 MCP 서버를 Claude에 연결하면 대화 한 줄로 두 가지 일을 모두 할 수 있습니다. 하나는 “강남역 근처 스시 맛집 알려줘” 같은 장소 검색(키워드·카테고리 검색), 다른 하나는 주소를 좌표로(지오코딩), 좌표를 행정구역·지번 주소로(리버스 지오코딩) 바꾸는 변환 작업입니다. 둘 다 카카오 로컬 API 하나로 처리되며, 카카오 REST API 키만 있으면 별도 백엔드 없이 Claude Desktop이나 Claude Code에서 바로 쓸 수 있습니다.

이 가이드가 다루는 것

카카오 로컬 API는 장소 검색과 위치 데이터 변환을 모두 제공합니다. Claude와 결합하면 다음 작업을 자연어로 처리할 수 있습니다.

하고 싶은 일	사용하는 카카오 로컬 API	입력 → 출력
”광화문 카페 3곳 추천해줘”	키워드 장소 검색	검색어 → 장소 목록
”강남역 근처 편의점 찾아줘”	카테고리 장소 검색	카테고리·좌표 → 주변 장소
”서울시청 주소를 위도·경도로 바꿔줘”	주소 검색(지오코딩)	주소 문자열 → 위경도
”이 좌표가 어느 행정구역인지 알려줘”	좌표→주소(리버스 지오코딩)	위경도 → 행정구역·지번 주소
”WGS84 좌표를 카카오 좌표계로 변환해줘”	좌표계 변환	좌표계 A → 좌표계 B
”이 주소록 100건의 위경도를 채워줘”	지오코딩 일괄 처리	주소 목록 → 좌표 목록

맛집·관광지를 찾는 것뿐 아니라, 엑셀 주소록에 좌표를 채우거나 GPS 로그를 동 단위로 묶거나 좌표계가 다른 두 데이터셋을 합치는 작업까지 — 원래는 코드와 API 문서가 필요했던 일을 MCP로 연결하면 Claude가 직접 카카오 API를 호출하고 결과를 표나 목록으로 정리해 줍니다.

왜 MCP로 연결하나

카카오맵은 한국 최대 장소 데이터베이스 중 하나로, 음식점 리뷰·영업시간·위치 정보를 제공합니다. 기존에는 이 데이터를 활용하려면 REST API 문서를 읽고 HTTP 요청을 직접 작성한 뒤 JSON 응답을 파싱하는 코드를 따로 짜야 했습니다. MCP(Model Context Protocol)는 이 과정을 표준 인터페이스로 대체합니다.

항목	MCP 연결 전	MCP 연결 후
검색·변환 방법	HTTP 요청 코드 직접 작성	자연어 프롬프트
API 문서 참조	필수	불필요
응답 파싱	개발자가 직접 처리	Claude가 해석·요약
활용 가능 사용자	개발자 위주	누구나
추가 맥락 결합	별도 코딩 필요	Claude가 자동 종합

[Claude Desktop / Claude Code / Cursor 등]
        │  MCP stdio 통신
        ▼
[카카오맵 MCP 서버] ── 환경 변수에서 REST API 키 로드
        │  HTTPS 요청 (키워드·카테고리 검색 / 지오코딩 / 좌표 변환)
        ▼
[카카오 로컬 API]  (dapi.kakao.com/v2/local/...)
        │  JSON 응답 (장소명·주소·위경도 / 행정구역·지번)
        ▼
[MCP 서버가 결과 파싱 → Claude로 전달]
        │
        ▼
[Claude가 자연어로 결과 정리·요약]

Claude Desktop이 MCP 서버를 로컬 프로세스로 실행하고, 서버가 카카오 로컬 API와 통신하는 구조입니다. REST API 키는 환경 변수로만 관리되어 대화 내용이나 Claude 본체에 직접 노출되지 않습니다.

준비물

• 카카오 계정 — 카카오 개발자 콘솔 로그인에 필요(무료)
• 카카오 REST API 키 — developers.kakao.com에서 무료 발급(무료 쿼터 제공)
• Node.js 18 이상(또는 서버 구현에 따라 Python 3.10 이상)
• Git — 저장소 클론용
• Claude Desktop 또는 Claude Code CLI — Claude Desktop은 claude.ai/download에서 설치

준비물만 갖추면 약 20분이면 설정을 완료할 수 있습니다.

단계별 설치

1단계 — 카카오 REST API 키 발급

1. 카카오 개발자 콘솔에 카카오 계정으로 로그인합니다.
2. 상단 내 애플리케이션 → 애플리케이션 추가하기를 클릭하고 앱 이름을 입력합니다(예: kakao-mcp-local). 사업자명은 개인 프로젝트라면 임의 입력해도 됩니다.
3. 생성된 앱의 앱 키 탭에서 REST API 키를 복사합니다. JavaScript 키나 Admin 키가 아닌 REST API 키를 사용해야 합니다.
4. 좌측 사이드바에서 카카오 로컬 또는 지도 항목을 확인해 API 사용이 활성화 상태인지 점검합니다(신규 앱은 기본 활성 상태입니다).
5. 앱 설정 → 플랫폼 → Web 플랫폼 등록에서 로컬 테스트용으로 http://localhost를 허용 도메인에 추가해 둡니다.

허용 도메인을 등록하지 않으면 일부 API에서 도메인 검증 오류가 발생할 수 있습니다. 로컬에서 MCP 서버를 돌리더라도 http://localhost는 미리 넣어 두는 것이 안전합니다.

2단계 — 카카오맵 MCP 서버 설치

카카오맵 MCP 서버는 GitHub에 여러 오픈소스 구현체가 공개되어 있습니다. 키워드·카테고리 검색만 노출하는지, 지오코딩·좌표 변환 도구까지 노출하는지는 구현체마다 다르므로, 카카오·네이버 카테고리에서 현재 등록된 서버 목록과 각 저장소의 README를 먼저 확인하세요.

대상 서버를 정했다면 저장소를 클론하고 의존성을 설치합니다. Node.js 기반 서버의 경우:

git clone https://github.com/{저장소-주소}
cd {저장소-폴더명}
npm install

Python 기반 서버의 경우:

git clone https://github.com/{저장소-주소}
cd {저장소-폴더명}
pip install -r requirements.txt

진입점 파일명, 빌드 필요 여부, 환경 변수명은 저장소마다 다릅니다. 빌드가 필요한 서버라면 README의 안내(예: npm run build 후 dist/index.js 생성)를 따른 뒤, 생성된 실행 파일 경로를 다음 단계에서 사용합니다.

3단계 — 환경 변수에 REST API 키 설정

발급받은 카카오 REST API 키를 MCP 서버가 읽을 수 있게 설정합니다. 저장소가 .env 파일을 지원하는 경우, 프로젝트 루트에 아래처럼 생성합니다.

# .env 파일 예시 (저장소 루트에 생성)
KAKAO_REST_API_KEY=여기에_발급받은_REST_API_키_입력

변수명은 각 MCP 서버 저장소의 README에서 확인해야 합니다. 서버마다 KAKAO_REST_API_KEY, KAKAO_API_KEY 등 환경 변수명이 다를 수 있습니다. .env 파일은 절대 Git에 커밋하지 마세요. .gitignore에 .env가 포함돼 있는지 반드시 확인하세요.

키를 아래 단계처럼 Claude 설정 파일의 env 블록에 직접 넣는다면 별도 .env는 필요 없습니다.

4단계 — Claude Desktop 설정 파일 편집

설정 파일 위치는 운영체제별로 다릅니다.

운영체제	경로
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json

mcpServers 항목에 아래를 추가합니다. Node.js 기반 서버 예시입니다.

{
  "mcpServers": {
    "kakao-map": {
      "command": "node",
      "args": ["/절대경로/kakao-map-server/dist/index.js"],
      "env": {
        "KAKAO_REST_API_KEY": "여기에_REST_API_키_입력"
      }
    }
  }
}

Python 기반 서버라면 아래처럼 설정합니다.

{
  "mcpServers": {
    "kakao-map": {
      "command": "python",
      "args": ["/절대경로/kakao-map-server/server.py"],
      "env": {
        "KAKAO_REST_API_KEY": "여기에_REST_API_키_입력"
      }
    }
  }
}

/절대경로/는 실제로 클론한 디렉터리의 절대 경로로 바꿉니다. macOS에서는 ~/ 대신 /Users/사용자명/ 형식을 사용하세요. 환경 변수명(KAKAO_REST_API_KEY 등)은 서버 구현에 따라 다를 수 있으니 README 기준으로 맞춥니다.

기존에 다른 MCP 서버가 등록돼 있다면 mcpServers 객체 안에 나란히 추가하면 됩니다.

{
  "mcpServers": {
    "기존-서버": { "command": "...", "args": [] },
    "kakao-map": {
      "command": "node",
      "args": ["/절대경로/kakao-map-server/dist/index.js"],
      "env": {
        "KAKAO_REST_API_KEY": "여기에_REST_API_키_입력"
      }
    }
  }
}

5단계 — Claude Code(CLI) 사용자 설정

Claude Code를 주로 쓴다면 프로젝트 루트의 .claude/settings.json 또는 글로벌 설정에 동일한 구조로 등록합니다. Claude Desktop 설정과 형식이 같습니다.

{
  "mcpServers": {
    "kakao-map": {
      "command": "node",
      "args": ["/절대경로/kakao-map-server/dist/index.js"],
      "env": {
        "KAKAO_REST_API_KEY": "여기에_REST_API_키_입력"
      }
    }
  }
}

6단계 — 동작 확인

설정 파일을 저장한 뒤 Claude Desktop을 완전히 종료하고(macOS는 독뿐 아니라 메뉴바 트레이까지) 다시 실행합니다. 새 대화에서 장소 검색과 변환을 모두 시험해 보세요.

장소 검색:

• “강남역 근처 스시 맛집 5곳 알려줘”
• “홍대 근처 24시간 편의점 위치 찾아줘”
• “제주시 애월읍 카페 추천해줘”
• “서울 광화문 주변 관광지 알려줘”

주소·좌표 변환:

카카오맵으로 "서울특별시 중구 세종대로 110" 주소를 위도·경도로 변환해줘.

위도 37.5666, 경도 126.9784가 어느 행정구역에 속하는지 카카오맵으로 알려줘.

Claude가 카카오맵 MCP 도구를 호출해 장소 목록(장소명·주소·카카오맵 링크 등)이나 좌표·행정구역을 반환하면 연결 성공입니다.

카카오 로컬 API 엔드포인트

MCP 서버가 실제로 어떤 도구를 노출하는지는 저장소 README에서 확인하세요. 카카오 로컬 API의 주요 엔드포인트는 다음과 같습니다.

기능	설명	API 엔드포인트
키워드 장소 검색	검색어로 장소 목록 반환	/v2/local/search/keyword
카테고리 장소 검색	카페·음식점·병원 등 카테고리별	/v2/local/search/category
주소 검색(지오코딩)	주소 문자열 → 위도/경도	/v2/local/search/address
좌표 → 주소(리버스)	위도/경도 → 행정구역·지번 주소	/v2/local/geo/coord2address
좌표계 변환	WGS84, WCONGNAMUL, KTM 등 좌표계 간 변환	/v2/local/geo/transcoord

설치 점검 체크리스트

연결이 안 될 때 아래를 위에서부터 확인하면 대부분 원인이 좁혀집니다.

• REST API 키를 사용했는가? (JavaScript 키·Admin 키 아님)
• 설정 파일의 환경 변수명이 서버 README가 요구하는 이름과 정확히 일치하는가?
• args 경로가 실제 실행 파일의 절대 경로인가?
• 설정 파일이 유효한 JSON인가? (쉼표·중괄호 누락 확인)
• Claude를 트레이까지 완전히 종료 후 재시작했는가?
• 카카오 개발자 콘솔에 http://localhost를 허용 도메인으로 등록했는가?

흔한 오류와 해결법

”Server disconnected” / 서버가 연결되지 않음

설정 파일의 args 경로가 잘못됐거나, 실행 명령(command)을 시스템이 찾지 못하는 경우입니다. 아래로 실행 파일의 절대 경로를 확인하세요.

# Node.js 경로 확인
which node

# Python 경로 확인
which python3

확인한 절대 경로를 설정 파일의 "command" 값으로 직접 지정하면 환경 변수(PATH) 문제를 우회할 수 있습니다. 예를 들어 "command": "/usr/local/bin/node"처럼 명시합니다.

401 Unauthorized / Invalid REST API key

KAKAO_REST_API_KEY 값과 변수명을 확인하세요. REST API 키가 맞는지, 설정 파일의 변수명이 서버가 읽는 이름과 일치하는지 점검합니다. 카카오 개발자 콘솔에서 해당 앱이 정상 상태이고 로컬 API 사용이 활성화돼 있는지도 확인하세요.

”허가되지 않은 도메인” 오류

카카오 개발자 콘솔 → 앱 → 플랫폼 → Web 플랫폼 등록에서 http://localhost를 추가합니다.

검색·변환 결과가 비어 있음

장소 검색에서 빈 결과가 나오면, 검색 키워드가 카카오맵에 등록된 업체명·카테고리와 일치하지 않는 경우가 많습니다. 변환(지오코딩)에서 빈 결과가 나오면, 입력이 카카오가 인식하는 표준 주소 형식이 아닌 경우가 흔합니다. “스타벅스 강남점” 같은 상호명은 주소 검색(/search/address)이 아니라 키워드 검색(/search/keyword) 대상이므로 빈 결과가 나올 수 있습니다. 도로명/지번 주소를 정확히 입력하거나, 장소명이라면 키워드 검색을 사용하세요. 카카오 개발자 콘솔의 테스트 도구로 같은 파라미터를 직접 호출해 API 응답을 먼저 확인하면 원인을 빠르게 가를 수 있습니다.

Claude Desktop 설정 파일 JSON 오류

설정 파일은 순수 JSON 형식이라 쉼표 하나, 중괄호 하나가 어긋나도 서버 전체가 실행되지 않습니다. JSONLint 같은 온라인 도구나, macOS에서는 다음으로 유효성을 검사할 수 있습니다.

cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python3 -m json.tool

오류 없이 출력되면 문법은 정상입니다. 그래도 MCP 서버가 안 보이면 args의 실행 파일 경로를 절대 경로로 다시 확인하고, 터미널에서 MCP 서버를 직접 실행해 오류 메시지를 확인하세요.

Node.js 버전 오류

node --version

v18 미만이면 Node.js 공식 사이트에서 LTS 버전을 설치하세요.

함께 쓰면 좋은 한국 MCP 서버

카카오맵 외에도 한국 주요 서비스를 AI에 연결하는 MCP 서버들이 있습니다.

한국어 맞춤법 검사 MCP

한국어 맞춤법 검사 MCP는 네이버 맞춤법 검사기를 활용해 한국어 텍스트의 철자·문법을 자동 교정합니다. API 키 없이 바로 쓸 수 있어, 카카오맵으로 정리한 위치 정보를 글로 작성할 때 함께 활용하면 좋습니다.

npx -y @winterjung/mcp-korean-spell

GitHub 저장소는 https://github.com/winterjung/mcp-korean-spell에서 확인할 수 있습니다.

에이전트웹서치 MCP

에이전트웹서치 MCP는 API 키 없이 Chrome CDP로 네이버·구글·Brave를 병렬 검색합니다. 주소를 좌표로 변환하거나 장소를 검색한 뒤, 해당 지역의 최신 리뷰·블로그 후기를 웹 검색으로 보완하는 데 활용할 수 있습니다. GitHub 저장소는 https://github.com/insung8150/AgentWebSearch-MCP를 참고하세요.

네이웍스 MCP 서버

네이웍스 MCP 서버는 LINE WORKS(NAVER WORKS) 전용 MCP 서버로, 메시지·캘린더·드라이브·메일·할일·게시판 등 26개 도구를 제공합니다. 카카오맵으로 약속 장소를 검색·정리한 뒤 LINE WORKS 캘린더에 일정을 등록하는 워크플로를 자동화할 수 있습니다.

npx nworks mcp

GitHub 저장소는 https://github.com/yjcho9317/nworks이며, API 키는 developers.worksmobile.com에서 발급받을 수 있습니다.

더 많은 서버는 카카오·네이버 카테고리와 전체 서버 목록에서 확인하세요.

자주 묻는 질문

카카오맵 MCP로 검색할 수 있는 장소 유형은 무엇인가요?

카카오 로컬 API의 키워드 검색과 카테고리 검색을 지원하는 MCP 서버라면 음식점, 카페, 관광지, 편의점, 병원, 주차장, 숙박 등 카카오맵에 등록된 모든 업종·장소를 검색할 수 있습니다. 반경 지정, 위경도 기준 주변 검색, 행정구역 기반 검색 등도 API에서 지원합니다.

지오코딩과 장소 검색은 무엇이 다른가요?

지오코딩(주소 검색)은 정형화된 주소 문자열을 위경도로 바꾸는 기능이고, 키워드 검색은 상호명·업종 같은 자유 검색어로 장소 목록을 찾는 기능입니다. “서울특별시 중구 세종대로 110”은 지오코딩, “광화문 카페”는 키워드 검색에 적합합니다. 입력이 주소면 search/address, 상호·업종이면 search/keyword를 쓴다고 기억하면 됩니다.

좌표계 변환(transcoord)은 언제 필요한가요?

데이터마다 사용하는 좌표계가 다를 때 필요합니다. 일반적인 GPS 위경도는 WGS84이지만, 일부 국내 지도·공공 데이터는 WCONGNAMUL이나 KTM 같은 좌표계를 씁니다. 서로 다른 좌표계의 데이터를 합치거나 카카오맵 위에 표시하려면 /v2/local/geo/transcoord로 변환해야 합니다.

카카오 로컬 API는 유료인가요?

카카오 로컬 API는 무료 쿼터를 제공하며, 개인·소규모 프로젝트 수준의 요청량은 무료 범위에서 충분히 처리할 수 있습니다. 대규모·상업적 이용 시에는 카카오 개발자 콘솔의 정책을 확인하세요.

Claude Desktop 외 다른 클라이언트에서도 쓸 수 있나요?

네. MCP를 지원하는 Claude Code, Cursor, Zed, Windsurf 등에서 동일한 mcpServers 설정 방식으로 연결할 수 있습니다.

Windows에서도 설치할 수 있나요?

네. Node.js(또는 Python)와 Git이 설치된 Windows에서 동일한 절차로 진행하면 됩니다. 설정 파일 경로는 %APPDATA%\Claude\claude_desktop_config.json입니다.

API 키를 설정 파일에 직접 적어도 되나요?

가능하지만 설정 파일을 Git에 올린다면 키가 노출됩니다. .gitignore에 설정 파일이나 .env를 추가하고, 가능하면 키를 별도 환경 변수로 분리해 관리하세요.

다음 단계

장소 검색과 지오코딩·좌표 변환을 Claude에 연결했다면 위치 데이터 가공을 통째로 맡길 수 있습니다. 동네 맛집·주말 여행지를 자연어로 물어보는 것은 물론, 주소록에 위경도 일괄 채우기, GPS 로그를 행정구역별로 묶기, 좌표계가 다른 데이터셋 병합 같은 작업도 지시해 보세요.

다른 한국 MCP 서버가 궁금하면 카카오·네이버 카테고리와 MCP모아 가이드 목록을 둘러보세요. 직접 만든 MCP 서버가 있다면 서버 등록도 환영합니다.