아래의 주소를 이용하면, markdown 원본을 확인할 수 있어요. 이 페이지의 내용을 마크다운 형식으로 복사할 때 편리하고, 토큰 효율도 좋아요.
Markdown 복사
사용 중인 AI 도구에서 INAVI Maps API MCP 서버를 연결해 보세요. API MCP 서버는 INAVI Maps API를 직접 호출하므로 APPKEY가 필요합니다. 상세한 내용은 시작 가이드 에서 확인하실 수 있습니다. APPKEY 발급 후 아래 설정을 각 AI 도구의 서버 설정 경로에 추가하고, MY_APPKEY 를 실제 APPKEY로 바꾼 뒤 AI 도구를 재시작하면 됩니다. (Codex는 JSON이 아닌 TOML 형식이라 변환이 필요해요.)
4
tool
도구
path
설정 경로
config
서버 설정
cursor
Cursor
~/.cursor/mcp.json
json
{ "mcpServers": { "inavi-maps-api": { "command": "npx", "args": ["-y", "@inavi-maps/api-mcp-server"], "env": { "INAVI_APPKEY": "MY_APPKEY" } } } }
https://cursor.com/docs/mcp
claude-code
* Claude Code
~/.claude.json
json
{ "mcpServers": { "inavi-maps-api": { "command": "npx", "args": ["-y", "@inavi-maps/api-mcp-server"], "env": { "INAVI_APPKEY": "MY_APPKEY" } } } }
https://code.claude.com/docs/en/mcp
claude-desktop
Claude Desktop
%APPDATA%\Claude\claude_desktop_config.json
json
{ "mcpServers": { "inavi-maps-api": { "command": "npx", "args": ["-y", "@inavi-maps/api-mcp-server"], "env": { "INAVI_APPKEY": "MY_APPKEY" } } } }
https://modelcontextprotocol.io/docs/develop/connect-local-servers
windsurf
Windsurf
~/.codeium/windsurf/mcp_config.json
json
{ "mcpServers": { "inavi-maps-api": { "command": "npx", "args": ["-y", "@inavi-maps/api-mcp-server"], "env": { "INAVI_APPKEY": "MY_APPKEY" } } } }
https://docs.windsurf.com/windsurf/cascade/mcp
vscode
VS Code
사용자 프로필
json
{ "servers": { "inavi-maps-api": { "command": "npx", "args": ["-y", "@inavi-maps/api-mcp-server"], "env": { "INAVI_APPKEY": "MY_APPKEY" } } } }
https://code.visualstudio.com/docs/agents/reference/mcp-configuration
codex
* Codex
~/.codex/config.toml
toml
[mcp_servers.inavi-maps-api] command = "npx" args = ["-y", "@inavi-maps/api-mcp-server"] env = { INAVI_APPKEY = "MY_APPKEY" }
https://developers.openai.com/codex/mcp
* Claude Code, Codex와 같은 CLI 도구는 다음과 같이 간단하게 설정할 수 있어요.
Claude Code
claude mcp add --transport stdio inavi-maps-api --env INAVI_APPKEY=MY_APPKEY -- npx -y @inavi-maps/api-mcp-server
Codex
codex mcp add inavi-maps-api --env INAVI_APPKEY=MY_APPKEY -- npx -y @inavi-maps/api-mcp-server
API MCP 서버는 APPKEY 없이 시작되지 않습니다. 서버 설정의 INAVI_APPKEY 에 발급받은 APPKEY를 꼭 넣어 주세요.
지도는 MCP Apps를 지원하는 MCP Host 에서만 보입니다. 지원하지 않는 호스트에서도 도구 호출과 응답은 그대로 동작하고, 지도만 그려지지 않습니다.
INAVI Maps API MCP 서버는 INAVI Maps API를 호출하는 총 11개의 도구를 제공합니다. lookup_category_code 를 제외한 10개의 도구는 결과를 지도로 표시할 수 있습니다.
도구
설명
지도 표시
search_places
상호명·건물명·업종·주소·전화번호로 장소와 주소를 검색합니다. 한국어·영어·일본어·중국어를 지원합니다
search_nearby_category
한 지점 주변(반경·사각 영역)에서 같은 분류의 장소를 모두 찾습니다
geocode_address
주소를 좌표로 바꿉니다
reverse_geocode
좌표를 주소·행정구역 코드·가장 가까운 건물 이름으로 바꿉니다
find_entry_points
경로 탐색 전에 좌표를 차량 진입로·택시 승하차 지점으로 보정합니다
get_admin_boundary
시도·시군구·읍면동·리의 행정구역 경계를 가져옵니다
find_route
경유지 최대 5개의 자동차 경로를 실시간 또는 출발·도착 시각 기준으로 탐색합니다
find_walking_route
계단·엘리베이터 같은 시설 정보를 담은 도보·킥보드(PM) 경로를 탐색합니다
optimize_waypoint_order
경유지 최대 10곳의 최적 방문 순서를 구합니다
get_distance_matrix
여러 지점 사이의 거리·시간 행렬을 구합니다
lookup_category_code
분류 이름으로 분류 코드를 찾습니다 (API를 호출하지 않습니다)
지도는 결과를 보여 주는 데서 끝나지 않습니다. 대화의 흐름이 끊기지 않도록 지도 안에서 옵션을 바꿔 도구를 다시 호출할 수 있습니다.
결과
지도에서 하는 일
장소 검색
언어 바꾸기 · 페이지 넘기기 · 현재 지도에서 재검색 · 경로 만들기 프롬프트 생성
주변 분류 검색
페이지 넘기기 · 경로 만들기 프롬프트 생성
지오코딩
페이지 넘기기
자동차 경로
탐색 기준 변경(추천·무료 도로·고속도로) · 차종 변경
도보 경로
이동 수단 변경(도보·킥보드) · 탐색 기준 변경
거리·시간 행렬
실시간 교통 반영
모든 지도에서 지도 유형(일반·항공·하이브리드·지형)과 밝은·어두운 테마를 바꿀 수 있고, MCP Host가 지원하면 전체화면으로 볼 수 있습니다.
MCP 서버 설치 후, AI에게 다음과 같이 자연어로 요청하실 수 있습니다. 결과를 지도로 보고 싶다면 지도에 보여줘 를 함께 요청하세요. Claude Desktop 등 일부 MCP Host는 다른 지도 도구를 기본으로 사용할 수 있으니, 요청 끝에 INAVI MCP를 사용해줘 를 붙이는 것을 추천합니다. 실제 답변 내용은 제공되는 예시와 다를 수 있습니다.
place-search
장소 검색
판교역 주변 스타벅스 찾아서 지도에 보여줘. INAVI MCP를 사용해줘
place
판교역 주변 스타벅스 검색 결과를 대화 안의 지도로 표시한 화면
route-search
경로 탐색
판교역에서 강남역까지 이동 경로를 지도에 보여줘. INAVI MCP를 사용해줘.
route
판교역에서 강남역까지 자동차 경로를 대화 안의 지도로 표시한 화면
API MCP 서버는 INAVI Maps API를 직접 호출하므로 APPKEY가 반드시 필요합니다. MCP 서버 자체는 무료로 제공되며, API 사용량에 따른 요금은 별도로 적용됩니다. 요금에 대한 자세한 설명은 요금 소개 를 참고해 주세요.
연동이 잘 안된다면 아래 항목을 체크해 보세요!
APPKEY 확인: 서버 설정의 env 에 INAVI_APPKEY 가 있는지 확인하세요. 없으면 서버가 시작되지 않습니다. Node.js 버전 확인: Node.js 22 이상이 필요합니다. 터미널에서 node -v 명령어로 확인하실 수 있습니다. 설정 파일 확인: JSON 문법 오류가 없는지 확인하세요. MCP Host 재시작: 설정 변경 후에는 도구를 완전히 종료했다가 다시 실행하세요.
해당 경로에 폴더나 파일이 존재하지 않는 경우, 직접 해당 폴더 및 .json (또는 .toml ) 파일을 생성하여 설정을 작성하시면 정상적으로 인식됩니다.
사용 중인 AI 도구에 맞는 작성 형식(JSON / TOML) 및 키 이름을 확인해 주세요. Codex: JSON이 아닌 TOML 형식 [mcp_servers.inavi-maps-api] 으로 작성해야 합니다. VS Code: 최상위 키 이름이 "mcpServers" 가 아닌 "servers" 로 설정되어야 합니다.
INAVI_APPKEY 에 입력한 APPKEY 값이 올바른지 확인해 주세요.
정상 동작입니다. 결과를 지도로 보고 싶다면 요청에 지도에 보여줘 를 함께 붙여 주세요. 지도는 MCP Apps를 지원하는 MCP Host에서만 표시됩니다.
imaps.inavi.com 에 접근할 수 있는지 확인해 주세요. 사내망 방화벽 등으로 차단된 경우 지도가 표시되지 않습니다.
개발하시다 궁금한 점이 생기면 아래 채널로 편하게 연락 주세요.
mcp-technical-help
MCP 서버 설정 및 연동 가이드
devbaek@inavi.kr
mcp-service-inquiry
INAVI Maps 서비스 도입 및 계정 문의
impsbiz@inavi.kr
mcp-developer-community
개발자 커뮤니티 및 질문 게시판
INAVI Maps 개발문의 바로가기