M MCP모아
튜토리얼

카카오모빌리티 MCP 설정 방법 — AI 에이전트에서 자동차 길찾기 연동하기

카카오모빌리티 길찾기 API를 MCP 서버로 감싸 Claude Desktop·Claude Code에서 자동차 경로 안내를 바로 사용하는 방법을 단계별로 설명합니다. API 키 발급부터 Claude 연동까지.

카카오모빌리티 길찾기 API와 Claude가 MCP 서버를 통해 자동차 경로를 주고받는 데이터 흐름도

카카오모빌리티 API를 MCP 서버로 감싸면 Claude Desktop에서 “서울역에서 인천공항까지 자동차로 얼마나 걸려?” 한 마디로 경로와 소요 시간을 바로 받을 수 있습니다. 이 가이드는 카카오 개발자 센터에서 API 키를 발급받고, Node.js 기반 MCP 서버를 직접 구성해 Claude에 연결하는 과정을 단계별로 안내합니다. 별도 패키지 없이 MCP SDK와 카카오 REST API만으로 30~40분 안에 완성할 수 있습니다.

카카오모빌리티 MCP가 필요한 이유

Claude나 다른 LLM은 기본 상태에서 실시간 교통 데이터나 구체적인 경로 정보를 제공하지 못합니다. 대화 중에 “이 두 주소 사이 거리 계산해줘”라고 해도 근사치 추정에 그칩니다. 반면 카카오모빌리티 API는 실제 도로망과 실시간 교통 상황을 반영한 자동차·도보·대중교통 경로를 반환합니다.

MCP(Model Context Protocol)는 AI 클라이언트가 외부 도구를 표준화된 방식으로 호출할 수 있게 해주는 프로토콜입니다. 카카오모빌리티 MCP 서버를 구성하면 Claude가 대화 흐름 안에서 길찾기 API를 직접 호출하고, 반환된 경로 데이터를 해석해 자연어로 설명해 줍니다. 배송 경로 최적화, 업무 출장 일정 계획, 부동산 접근성 분석 등 위치 기반 작업을 Claude와 함께 처리할 때 특히 유용합니다.

데이터 흐름 구조

사용자 질문 (출발지·목적지 입력)
        │
        ▼
Claude Desktop (MCP 클라이언트)
        │  MCP 프로토콜 (JSON-RPC over stdio)
        ▼
카카오모빌리티 MCP 서버 (로컬 Node.js 프로세스)
        │  HTTPS REST API 호출
        ▼
카카오모빌리티 길찾기 API (api-maps.kakao.com)
        │  JSON 경로 데이터 응답
        ▼
Claude가 경로·거리·소요 시간 해석 → 자연어 답변

준비물

항목설명필수 여부
Claude DesktopAnthropic 공식 데스크톱 앱 (claude.ai/download)필수
Node.js 18 이상MCP 서버 실행 환경필수
카카오 REST API 키카카오 개발자 센터 발급필수
npmNode.js와 함께 설치됨필수
터미널 (macOS/Linux/Windows)명령어 실행필수

카카오 API 키 발급과 Claude Desktop 설치가 없는 경우 아래 1단계부터 순서대로 진행하세요.

단계별 설치 및 설정 방법

1단계: 카카오 개발자 센터에서 API 키 발급

카카오모빌리티 길찾기 API는 카카오맵 플랫폼을 통해 제공됩니다. REST API 키를 발급받으세요.

  1. https://developers.kakao.com 접속 후 카카오 계정으로 로그인
  2. 상단 메뉴 내 애플리케이션 클릭 → 애플리케이션 추가하기
  3. 앱 이름과 사업자 이름(개인 사용 시 본인 이름)을 입력하고 저장
  4. 생성된 앱의 앱 키 탭에서 REST API 키(32자 영숫자)를 복사

카카오 개발자 센터에서 앱을 생성하면 REST API 키가 즉시 발급됩니다. 길찾기 API 사용량은 카카오 개발자 콘솔에서 모니터링할 수 있으며, 대량 호출 시에는 요금 정책을 카카오 공식 문서에서 반드시 확인하세요.

2단계: Node.js MCP 서버 프로젝트 생성

로컬에 새 디렉터리를 만들고 필요한 패키지를 설치합니다.

# 프로젝트 디렉터리 생성
mkdir kakao-mobility-mcp && cd kakao-mobility-mcp

# Node.js 패키지 초기화
npm init -y

# MCP SDK 및 HTTP 클라이언트 설치
npm install @modelcontextprotocol/sdk node-fetch dotenv

설치가 완료되면 package.json의 "type" 필드를 "module"로 변경해 ES 모듈을 사용합니다.

{
  "name": "kakao-mobility-mcp",
  "version": "1.0.0",
  "type": "module",
  "main": "index.js",
  "scripts": {
    "start": "node index.js"
  }
}

3단계: 환경 변수 파일(.env) 작성

프로젝트 루트에 .env 파일을 생성하고 1단계에서 복사한 REST API 키를 입력합니다.

touch .env

.env 파일 내용:

KAKAO_REST_API_KEY=여기에_발급받은_REST_API_키_입력

보안을 위해 .gitignore에 .env를 추가하세요.

echo ".env" >> .gitignore

4단계: MCP 서버 코드(index.js) 작성

아래 코드를 index.js로 저장합니다. 카카오모빌리티 자동차 길찾기 API(/v1/directions)를 호출하는 get_directions 도구를 구현합니다.

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";
import fetch from "node-fetch";
import "dotenv/config";

const KAKAO_KEY = process.env.KAKAO_REST_API_KEY;
const DIRECTIONS_URL = "https://apis-navi.kakaomobility.com/v1/directions";

const server = new Server(
  { name: "kakao-mobility-mcp", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

// 도구 목록 반환
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: "get_directions",
      description:
        "카카오모빌리티 API로 자동차 길찾기 경로를 조회합니다. 출발지·목적지를 경도/위도로 입력받아 거리(m)와 소요 시간(초)을 반환합니다.",
      inputSchema: {
        type: "object",
        properties: {
          origin: {
            type: "string",
            description: "출발지 경도,위도 (예: 126.9748677,37.5663174)",
          },
          destination: {
            type: "string",
            description: "목적지 경도,위도 (예: 126.4707902,37.4490003)",
          },
          priority: {
            type: "string",
            enum: ["RECOMMEND", "TIME", "DISTANCE"],
            description: "경로 우선순위 (기본값: RECOMMEND)",
          },
        },
        required: ["origin", "destination"],
      },
    },
  ],
}));

// 도구 실행
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name !== "get_directions") {
    throw new Error("Unknown tool");
  }

  const { origin, destination, priority = "RECOMMEND" } = request.params.arguments;

  const params = new URLSearchParams({ origin, destination, priority });
  const res = await fetch(`${DIRECTIONS_URL}?${params}`, {
    headers: {
      Authorization: `KakaoAK ${KAKAO_KEY}`,
      "Content-Type": "application/json",
    },
  });

  if (!res.ok) {
    const errText = await res.text();
    return {
      content: [
        {
          type: "text",
          text: `카카오 API 오류 (${res.status}): ${errText}`,
        },
      ],
    };
  }

  const data = await res.json();
  const route = data.routes?.[0];

  if (!route || route.result_code !== 0) {
    return {
      content: [
        {
          type: "text",
          text: `경로를 찾을 수 없습니다. 좌표가 올바른지 확인하세요. (result_code: ${route?.result_code})`,
        },
      ],
    };
  }

  const summary = route.summary;
  const distanceKm = (summary.distance / 1000).toFixed(1);
  const durationMin = Math.round(summary.duration / 60);

  return {
    content: [
      {
        type: "text",
        text: [
          `출발지: ${origin}`,
          `목적지: ${destination}`,
          `총 거리: ${distanceKm} km`,
          `예상 소요 시간: ${durationMin}분`,
          `경로 우선순위: ${priority}`,
          `요금 정보: ${summary.fare?.taxi ?? 0}원 (택시 기준)`,
        ].join("\n"),
      },
    ],
  };
});

const transport = new StdioServerTransport();
await server.connect(transport);

참고: 카카오모빌리티 API는 좌표를 경도,위도 형식으로 받습니다. 주소를 좌표로 변환하려면 카카오 로컬 API(/v2/local/search/address)를 추가로 활용하거나, Claude에게 “서울역의 경도·위도는?” 하고 물어볼 수 있습니다(단, Claude의 내부 지식 기반 좌표이므로 정밀도를 검증하세요).

5단계: Claude Desktop 설정 파일에 MCP 서버 등록

Claude Desktop의 설정 파일을 열어 방금 만든 서버를 추가합니다.

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "kakao-mobility": {
      "command": "node",
      "args": ["/절대경로/kakao-mobility-mcp/index.js"],
      "env": {
        "KAKAO_REST_API_KEY": "여기에_REST_API_키_입력"
      }
    }
  }
}

/절대경로/를 실제 경로로 교체하세요. macOS/Linux에서는 프로젝트 디렉터리 안에서 pwd 명령을 실행하면 절대 경로를 확인할 수 있습니다.

6단계: Claude Desktop 재시작 및 동작 확인

설정 파일을 저장한 뒤 Claude Desktop을 완전히 종료하고 다시 시작합니다. 그런 다음 채팅창에 다음과 같이 입력해 보세요.

서울역(126.9748677, 37.5663174)에서 인천국제공항(126.4707902, 37.4490003)까지 자동차로 얼마나 걸려?

Claude가 get_directions 도구를 호출하고 거리·소요 시간·요금 정보를 응답하면 연결이 성공한 것입니다.

흔한 오류와 해결 방법

오류 증상주요 원인해결 방법
API 401 UnauthorizedREST API 키 오류 또는 누락.env 또는 설정 파일의 키 값 재확인
API 400 Bad Request좌표 형식 오류경도,위도 순서로 입력했는지 확인
경로를 찾을 수 없음도달 불가 좌표 또는 해상도 밖 지점국내 좌표인지, 값이 뒤집히지 않았는지 확인
MCP 서버 연결 안 됨파일 절대 경로 오류pwd로 확인한 절대 경로로 수정
node 명령 인식 실패Node.js 미설치 또는 PATH 미등록Node.js 18 이상 설치 후 터미널 재시작
”Unknown tool” 오류JSON-RPC 핸들러 미등록index.js 코드에서 ListToolsRequestSchema 핸들러 확인

좌표 확인 팁: 카카오맵(map.kakao.com)에서 원하는 장소를 마우스 오른쪽 버튼으로 클릭하면 해당 지점의 경도·위도를 확인할 수 있습니다.

활용 예시 — Claude와 함께할 수 있는 것들

카카오모빌리티 MCP 서버를 연결하면 다음과 같은 작업을 대화 형태로 처리할 수 있습니다.

활용 시나리오Claude 입력 예시
출장 일정 계획”회의 장소 3곳을 순서대로 방문할 때 최단 경로 추천해줘”
부동산 접근성 분석”이 아파트에서 강남구청까지 출퇴근 시간 계산해줘”
배송 루트 비교”물류 창고에서 5개 배송지까지 총 이동 거리를 계산해줘”
여행 동선 정리”제주도 주요 관광지를 하루에 돌 수 있는 자동차 경로 짜줘”

지도·위치 카테고리의 다른 MCP 서버

카카오모빌리티와 함께 활용하면 시너지가 나는 지도·위치 관련 MCP 서버들을 지도·위치 카테고리에서 찾아보세요. 장소 검색, 주소-좌표 변환, 주변 시설 조회 등 기능을 보완할 수 있습니다.

MCP모아에 등록된 전체 MCP 서버 목록을 통해 업무 자동화, 금융 데이터 조회, 공공 데이터 연동 등 다양한 한국형 MCP 서버도 함께 탐색해 보세요.

자주 묻는 질문

카카오 REST API 키는 무료로 발급받을 수 있나요?

네, 카카오 개발자 센터(developers.kakao.com)에서 앱을 생성하면 REST API 키를 무료로 발급받을 수 있습니다. 다만 카카오모빌리티 길찾기 API는 별도 호출 할당량이 적용되며, 대량 호출 시에는 유료 전환이 필요할 수 있으므로 카카오 공식 요금 정책을 사전에 확인하세요.

카카오모빌리티 API와 카카오맵 API는 같은 건가요?

카카오모빌리티 API는 카카오맵 플랫폼에서 제공하는 길찾기·경로 최적화 특화 API입니다. 카카오맵 API에는 지도 렌더링·장소 검색 등이 포함되며, 카카오모빌리티는 자동차·도보·자전거·대중교통 경로와 소요 시간 산출에 초점이 맞춰져 있습니다.

경유지가 여러 개인 경로도 조회할 수 있나요?

카카오모빌리티 자동차 길찾기 API는 최대 3개의 경유지(waypoints)를 지원합니다. MCP 서버의 도구 스키마에 waypoints 배열을 추가하면 Claude에게 “서울역 출발, 강남역 경유, 공항 도착 경로” 같은 요청을 처리할 수 있습니다.

Claude Code에서도 이 MCP 서버를 사용할 수 있나요?

네, 가능합니다. Claude Code에서는 프로젝트 루트의 .mcp.json 파일에 동일한 방식으로 서버를 등록하면 됩니다. CLI 환경에서 길찾기 데이터를 자동화 스크립트나 코드 생성 작업과 결합할 때 유용합니다.

MCP 서버 연결 후 Claude가 도구를 인식하지 못할 때 어떻게 하나요?

Claude Desktop을 완전히 종료하고 재시작하세요. 그래도 해결되지 않으면 claude_desktop_config.json의 JSON 문법을 점검하고, 서버 파일 절대 경로가 정확한지 확인하세요. 터미널에서 node /경로/index.js를 직접 실행해 오류 메시지를 확인하는 것이 가장 빠른 진단 방법입니다.

이 가이드 말고 이미 만들어진 카카오모빌리티 MCP 서버가 있나요?

현재 MCP모아에 등록된 전용 카카오모빌리티 MCP 서버는 없습니다. 오픈소스로 개발하셨다면 MCP모아 등록 페이지에서 등록해 주시면 한국 개발자 커뮤니티와 공유할 수 있습니다.

다음 단계

카카오모빌리티 MCP 서버 설정이 완료됐다면, 이제 Claude와 함께 더 복잡한 위치 기반 작업을 시작할 수 있습니다. 예를 들어 여러 배송지의 총 이동 거리를 계산하거나, 부동산 후보지의 주요 시설 접근성을 일괄 비교하는 등 반복적인 지도 작업을 Claude에게 맡겨 보세요.

지도·위치 카테고리의 다른 MCP 서버들을 조합하면 장소 검색, 주소 변환, 경로 안내를 하나의 대화 흐름 안에서 처리하는 AI 에이전트를 만들 수 있습니다. 카카오모빌리티 MCP 서버를 직접 개선하거나 새로운 버전을 만드셨다면 MCP모아에 등록해 커뮤니티와 공유해 주세요.