카카오맵 MCP 길찾기: Claude에서 도보·대중교통 경로 검색하기

Q: 자동차 경로(내비게이션)도 지원되나요?

카카오 Directions v1 API는 자동차 경로도 지원합니다. 단, 특정 MCP 서버가 어떤 이동 수단 모드를 구현했는지는 해당 서버의 README를 확인해야 합니다. 지원하지 않는 모드라면 '자동차 경로는 현재 지원하지 않습니다'라는 응답이 옵니다.

Q: 출발지·도착지에 주소 대신 좌표를 입력해도 되나요?

네. 카카오 Directions API는 위도·경도 좌표를 직접 입력할 수 있습니다. Claude에게 '위도 37.5, 경도 127.0에서 강남역까지 경로 알려줘'처럼 요청하면 됩니다. 주소도 내부적으로 좌표로 변환되어 처리됩니다.

카카오맵 MCP를 Claude에 연결하면 “강남역에서 홍대입구역까지 대중교통으로 어떻게 가?”라는 자연어 한 줄로 경로 정보를 받을 수 있습니다. 카카오 REST API 키 하나만 준비하면 도보·대중교통 경로 검색을 Claude Desktop이나 Claude Code에서 바로 쓸 수 있습니다. 이 가이드는 API 키 발급, MCP 서버 빌드, 설정 파일 등록, 길찾기 확인, 그리고 자주 막히는 오류 해결까지 한 번에 다룹니다.

카카오맵 MCP 길찾기가 필요한 이유

Claude는 기본 상태에서 실시간 인터넷에 연결되어 있지 않습니다. 그래서 지도 앱을 따로 열지 않고 대화 안에서 경로를 확인하거나, 여러 후보지의 이동 시간을 한꺼번에 비교하려면 매번 앱을 전환해야 하는 번거로움이 생깁니다.

MCP(Model Context Protocol)는 Claude가 외부 도구를 표준 방식으로 호출하게 해주는 프로토콜입니다. 카카오맵 MCP 서버를 등록하면 Claude가 카카오 Directions API를 직접 호출해 경로 데이터를 가져오고, 그 결과를 바로 요약·비교·표로 정리하는 작업까지 한 대화 안에서 이어서 처리할 수 있습니다.

특히 다음과 같은 상황에서 진가를 발휘합니다.

상황	활용 예시
출장 일정 계획	”부산역에서 해운대까지 대중교통으로 얼마나 걸려?”
후보 사무실 비교	”직원 5명의 집에서 각 후보 사무실까지 출퇴근 시간 비교해줘”
도보 관광 코스 설계	”경복궁에서 인사동을 거쳐 광화문까지 도보 경로 알려줘”
부동산 리서치	”이 아파트에서 회사까지 대중교통 소요 시간이 얼마야?”

데이터 흐름 한눈에 보기

사용자 자연어 요청
     ↓
Claude (LLM) — 의도 파악, 도구 선택
     ↓
카카오맵 MCP 서버 — 파라미터 변환
     ↓
카카오 Directions API (REST)
     ↓
경로 응답 (소요시간·거리·환승 정보)
     ↓
Claude — 결과 자연어 정리
     ↓
사용자 응답

MCP 서버는 Claude와 카카오 API 사이의 번역 계층입니다. 자연어 요청을 올바른 API 파라미터(출발지 좌표, 도착지 좌표, 이동 수단 모드 등)로 바꾸고, 돌아온 응답 JSON을 다시 Claude가 다룰 수 있는 형태로 넘겨줍니다. 따라서 사용자가 좌표나 모드 이름을 직접 외울 필요가 없습니다.

준비물

Node.js 18 이상 (LTS 권장) — MCP 서버 실행에 필요합니다.
카카오 개발자 계정 및 REST API 키 — 인증에 사용합니다.
Claude Desktop 또는 Claude Code CLI — MCP 서버를 등록할 클라이언트입니다.

단계별 설치 및 설정 방법

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

카카오 개발자 콘솔에 로그인한 뒤 상단 내 애플리케이션 > 애플리케이션 추가하기를 클릭하고 앱 이름(예: claude-kakao-map)을 입력합니다.

앱이 생성되면 앱 키 탭에서 REST API 키를 복사합니다. 같은 탭에 있는 JavaScript 키나 Admin 키가 아니라 반드시 REST API 키를 사용해야 합니다. 길찾기 호출은 이 키로 인증합니다.

길찾기 API는 Web 플랫폼 등록 없이도 서버 측에서 호출할 수 있습니다. 다만 장소 검색 등 다른 카카오 API를 함께 쓸 계획이라면 플랫폼 탭에서 http://localhost를 허용 도메인으로 미리 추가해 두는 것이 좋습니다.

2단계 — 카카오맵 MCP 서버 빌드

카카오맵 MCP 서버는 Node.js 기반으로 배포됩니다. 저장소를 클론한 뒤 의존성을 설치하고 빌드합니다.

# 저장소 클론 (PlayMCP 카카오맵 MCP 서버)
git clone https://github.com/PlayMcpMmo/kakao-map-server
cd kakao-map-server

# 의존성 설치
npm install

# 빌드
npm run build

빌드가 끝나면 dist/index.js(저장소에 따라 build/index.js) 파일이 생성됩니다. 이 파일의 절대 경로를 다음 단계 설정에서 사용하므로 메모해 두세요. 경로는 pwd 명령으로 현재 디렉터리를 확인하면 쉽게 알 수 있습니다.

참고: 최신 저장소 URL과 지원 기능 목록은 MCP모아 지도·위치 카테고리 또는 전체 서버 목록에서 확인할 수 있습니다. 저장소 주소나 빌드 산출물 경로가 바뀌었을 수 있으니 클론 직후 README를 먼저 확인하세요.

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

Claude Desktop의 설정 파일 위치는 운영체제마다 다릅니다.

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

설정 파일을 텍스트 편집기로 열어 mcpServers 항목에 아래 내용을 추가합니다. 파일이 비어 있거나 없다면 전체를 그대로 붙여 넣어도 됩니다.

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

/절대경로/ 부분은 2단계에서 확인한 실제 디렉터리 절대 경로로 바꿔야 합니다. macOS에서는 ~/ 축약 대신 /Users/사용자명/ 형식의 전체 경로를 사용하세요. 경로에 공백이 있어도 JSON 문자열 하나로 처리되므로 그대로 입력하면 됩니다.

4단계 — Claude Code CLI 사용자 설정

터미널 기반 Claude Code를 주로 쓴다면, 프로젝트 루트의 .claude/settings.json에 동일한 형식으로 추가합니다.

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

특정 프로젝트가 아니라 모든 프로젝트에서 쓰려면 같은 내용을 전역 설정 파일인 ~/.claude/settings.json에 추가합니다.

5단계 — 재시작 및 길찾기 확인

Claude Desktop을 완전히 종료한 뒤 다시 실행합니다(트레이/메뉴바 아이콘까지 종료해야 설정이 다시 로드됩니다). 새 대화 창을 열어 아래처럼 요청해 보세요.

카카오맵으로 서울역에서 홍대입구역까지 대중교통 경로를 알려줘.

Claude가 카카오맵 MCP 도구를 호출해 소요 시간, 환승 정보, 요금 등을 응답하면 연결에 성공한 것입니다. 도보 경로가 필요하면 아래처럼 요청합니다.

경복궁에서 인사동 쌈지길까지 도보 경로를 알려줘.

카카오맵 길찾기 API가 제공하는 정보

카카오 Directions API 응답에 포함되는 주요 데이터는 아래와 같습니다. MCP 서버가 이 정보를 Claude에게 넘기면, Claude가 자연어나 표 형식으로 정리합니다.

정보 항목	설명
총 소요 시간	이동 수단별 예상 소요 시간
총 거리	전체 이동 거리
환승 횟수	대중교통 이용 시 환승 정보
구간별 이동 수단	지하철·버스·도보 구간 구분
예상 요금	대중교통 요금
도보 거리	역·정류장에서 목적지까지 도보 거리

원본 응답에서 소요 시간은 초, 거리는 미터, 요금은 원 단위로 내려옵니다. Claude는 이를 분·킬로미터 등 읽기 쉬운 단위로 변환해 정리해 줍니다.

흔한 오류와 해결법

401 Unauthorized — API 키 오류

카카오 API에서 인증 오류가 나면 가장 먼저 KAKAO_REST_API_KEY 환경 변수 값을 확인하세요. 흔한 원인은 REST API 키가 아닌 JavaScript 키나 Admin 키를 붙여 넣은 경우입니다. 앱 키 탭에서 REST API 키를 다시 복사해 교체하고, 키 앞뒤에 따옴표나 공백이 섞이지 않았는지도 확인합니다.

MCP 서버가 Claude 도구 목록에 나타나지 않음

대부분 설정 파일의 JSON 문법 오류 또는 경로 문제입니다. 먼저 JSON 문법을 검증하세요.

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

오류 없이 JSON이 출력되면 문법은 정상입니다. 그래도 도구가 보이지 않으면 args에 적은 dist/index.js(또는 build/index.js) 파일이 실제로 존재하는지, 절대 경로 철자가 정확한지 다시 확인하세요. 설정을 고친 뒤에는 Claude를 다시 완전히 종료했다가 실행해야 반영됩니다.

Node.js 버전 오류

node --version

v18 미만이면 Node.js 공식 사이트에서 LTS 버전을 설치하세요. nvm을 쓴다면 nvm install --lts로 간단히 업그레이드할 수 있습니다.

”경로를 찾을 수 없습니다” 응답

출발지·도착지가 카카오 API에서 인식되지 않을 때 나타납니다. 다음 순서로 다시 시도해 보세요.

도로명 주소를 포함한 더 구체적인 주소로 바꿔 요청합니다.
모호한 건물명 대신 역명·랜드마크명으로 지정합니다.
그래도 안 되면 위도·경도 좌표를 직접 입력합니다(예: “위도 37.5, 경도 127.0에서…”).

길찾기 결과 활용 예시

카카오맵 MCP 길찾기를 실제로 어떻게 활용하는지 구체적인 프롬프트로 살펴봅니다.

여러 경로 비교:

판교역에서 강남역까지 대중교통과 도보 경로를 각각 알려주고, 소요 시간을 비교해줘.

업무용 데이터 추출:

아래 주소 5곳에서 서울시청까지 대중교통 소요 시간을 표로 정리해줘.
- 수원역, 인천시청, 성남시청, 고양시청, 의정부역

관광 일정 통합:

경복궁 → 창덕궁 → 북촌한옥마을 → 인사동 순서로 도보 경로와 각 구간 소요 시간을 알려줘.

이처럼 Claude는 경로 조회에 그치지 않고, 그 결과를 정리·비교·보고서화하는 작업까지 한 번의 대화에서 이어서 처리합니다.

자주 묻는 질문

카카오맵 MCP 길찾기 API는 무료로 사용할 수 있나요?

카카오 REST API는 월 300,000건까지 무료 쿼터를 제공합니다. 길찾기(Directions) API도 동일한 무료 티어에 포함되므로 개인·소규모 용도라면 무료로 충분합니다. 쿼터 초과 시 카카오 developers 요금 안내 페이지를 참고하세요.

도보 경로와 대중교통 경로를 동시에 비교할 수 있나요?

카카오 Directions API는 도보(walk)와 대중교통(transit) 모드를 각각 별도 호출로 지원합니다. Claude에게 “도보와 대중교통 경로를 둘 다 알려줘”라고 요청하면 MCP 서버가 두 번 API를 호출해 결과를 나란히 정리해 줍니다.

자동차 경로(내비게이션)도 지원되나요?

카카오 Directions v1 API는 자동차 경로도 지원합니다. 다만 특정 MCP 서버가 어떤 이동 수단 모드를 구현했는지는 해당 서버의 README를 확인해야 합니다. 서버가 지원하지 않는 모드라면 해당 기능을 지원하지 않는다는 응답이 반환됩니다.

출발지·도착지에 주소 대신 좌표를 입력해도 되나요?

네. 카카오 Directions API는 위도·경도 좌표를 직접 입력할 수 있습니다. Claude에게 “위도 37.5, 경도 127.0에서 강남역까지 경로 알려줘”처럼 요청하면 됩니다. 주소도 내부적으로 좌표로 변환되어 처리됩니다.

경로 결과에 소요 시간이 포함되나요?

네. API 응답에는 총 소요 시간(초 단위), 총 거리(미터), 대중교통의 경우 환승 횟수·요금·각 구간별 이동 수단 정보가 포함됩니다. Claude가 이를 읽기 쉬운 표나 자연어로 정리해 줍니다.

경로 검색 결과를 스프레드시트나 보고서로 만들 수 있나요?

Claude에게 결과를 마크다운 표·CSV·JSON 형식으로 정리해달라고 추가 요청하면 됩니다. 예를 들어 “출퇴근 가능한 역 5곳의 소요 시간을 표로 정리해줘”처럼 요청하면 데이터를 바로 보고서 형식으로 변환해 줍니다.

다음 단계

카카오맵 MCP 길찾기를 연결했다면, 경로 조회를 Claude의 다른 기능과 결합해 보세요. 여러 후보지의 소요 시간을 비교해 최적 지점을 고르거나, 방문 순서를 정리해 일정을 짜는 워크플로로 확장할 수 있습니다.

지도·위치 관련 다른 한국 MCP 서버가 궁금하다면 지도·위치 카테고리를 확인하세요. 다른 유형의 한국 MCP 서버는 전체 서버 목록에서, 다양한 활용 가이드는 가이드 목록에서 찾아볼 수 있습니다. 직접 만든 카카오맵 MCP 서버가 있다면 서버 등록도 환영합니다.