# API MCP 서버

API MCP 서버는 AI가 INAVI Maps API를 직접 호출해 장소·주소·경로를 찾고, 결과를 대화 안의 지도로 보여줄 수 있도록 지원합니다. 본 가이드는 사용 중인 AI 도구에 API MCP 서버를 연결하고 활용하는 방법을 안내합니다.

<!-- Section: 상세 내용 -->

### BANNER


### 마크다운으로 복사하기

아래의 주소를 이용하면, markdown 원본을 확인할 수 있어요. 이 페이지의 내용을 마크다운 형식으로 복사할 때 편리하고, 토큰 효율도 좋아요.


#### BUTTONTEXT

Markdown 복사


### SETUP


### 환경 설정

사용 중인 AI 도구에서 INAVI Maps API MCP 서버를 연결해 보세요. API MCP 서버는 INAVI Maps API를 직접 호출하므로 APPKEY가 필요합니다. 상세한 내용은 시작 가이드 에서 확인하실 수 있습니다. APPKEY 발급 후 아래 설정을 각 AI 도구의 서버 설정 경로에 추가하고, MY_APPKEY 를 실제 APPKEY로 바꾼 뒤 AI 도구를 재시작하면 됩니다. (Codex는 JSON이 아닌 TOML 형식이라 변환이 필요해요.)


#### CONFIGROWSPAN

4


#### HEADERS


##### KEY

tool


##### VALUE

도구


##### KEY

path


##### VALUE

설정 경로


##### KEY

config


##### VALUE

서버 설정


#### ITEMS


##### KEY

cursor


##### TOOL

Cursor


##### PATH

~/.cursor/mcp.json


##### CONFIGTYPE

json


##### CODE

{ "mcpServers": { "inavi-maps-api": { "command": "npx", "args": ["-y", "@inavi-maps/api-mcp-server"], "env": { "INAVI_APPKEY": "MY_APPKEY" } } } }


##### GUIDEURL

https://cursor.com/docs/mcp


##### KEY

claude-code


##### TOOL

* Claude Code


##### PATH

~/.claude.json


##### CONFIGTYPE

json


##### CODE

{ "mcpServers": { "inavi-maps-api": { "command": "npx", "args": ["-y", "@inavi-maps/api-mcp-server"], "env": { "INAVI_APPKEY": "MY_APPKEY" } } } }


##### GUIDEURL

https://code.claude.com/docs/en/mcp


##### KEY

claude-desktop


##### TOOL

Claude Desktop


##### PATH

%APPDATA%\Claude\claude_desktop_config.json


##### CONFIGTYPE

json


##### CODE

{ "mcpServers": { "inavi-maps-api": { "command": "npx", "args": ["-y", "@inavi-maps/api-mcp-server"], "env": { "INAVI_APPKEY": "MY_APPKEY" } } } }


##### GUIDEURL

https://modelcontextprotocol.io/docs/develop/connect-local-servers


##### KEY

windsurf


##### TOOL

Windsurf


##### PATH

~/.codeium/windsurf/mcp_config.json


##### CONFIGTYPE

json


##### CODE

{ "mcpServers": { "inavi-maps-api": { "command": "npx", "args": ["-y", "@inavi-maps/api-mcp-server"], "env": { "INAVI_APPKEY": "MY_APPKEY" } } } }


##### GUIDEURL

https://docs.windsurf.com/windsurf/cascade/mcp


##### KEY

vscode


##### TOOL

VS Code


##### PATH

사용자 프로필


##### CONFIGTYPE

json


##### CODE

{ "servers": { "inavi-maps-api": { "command": "npx", "args": ["-y", "@inavi-maps/api-mcp-server"], "env": { "INAVI_APPKEY": "MY_APPKEY" } } } }


##### GUIDEURL

https://code.visualstudio.com/docs/agents/reference/mcp-configuration


##### KEY

codex


##### TOOL

* Codex


##### PATH

~/.codex/config.toml


##### CONFIGTYPE

toml


##### CODE

[mcp_servers.inavi-maps-api] command = "npx" args = ["-y", "@inavi-maps/api-mcp-server"] env = { INAVI_APPKEY = "MY_APPKEY" }


##### GUIDEURL

https://developers.openai.com/codex/mcp


#### CLINOTETITLE

* Claude Code, Codex와 같은 CLI 도구는 다음과 같이 간단하게 설정할 수 있어요.


#### CLICOMMANDS


##### TOOL

Claude Code


##### COMMAND

claude mcp add --transport stdio inavi-maps-api --env INAVI_APPKEY=MY_APPKEY -- npx -y @inavi-maps/api-mcp-server


##### TOOL

Codex


##### COMMAND

codex mcp add inavi-maps-api --env INAVI_APPKEY=MY_APPKEY -- npx -y @inavi-maps/api-mcp-server


#### NOTES

API MCP 서버는 APPKEY 없이 시작되지 않습니다. 서버 설정의 INAVI_APPKEY 에 발급받은 APPKEY를 꼭 넣어 주세요.

지도는 MCP Apps를 지원하는 MCP Host 에서만 보입니다. 지원하지 않는 호스트에서도 도구 호출과 응답은 그대로 동작하고, 지도만 그려지지 않습니다.


### TOOLS


### 사용 가능한 도구

INAVI Maps API MCP 서버는 INAVI Maps API를 호출하는 총 11개의 도구를 제공합니다. lookup_category_code 를 제외한 10개의 도구는 결과를 지도로 표시할 수 있습니다.


#### TABLEHEADER

도구

설명

지도 표시


#### ITEMS


##### TOOL

search_places

상호명·건물명·업종·주소·전화번호로 장소와 주소를 검색합니다. 한국어·영어·일본어·중국어를 지원합니다


##### TOOL

search_nearby_category

한 지점 주변(반경·사각 영역)에서 같은 분류의 장소를 모두 찾습니다


##### TOOL

geocode_address

주소를 좌표로 바꿉니다


##### TOOL

reverse_geocode

좌표를 주소·행정구역 코드·가장 가까운 건물 이름으로 바꿉니다


##### TOOL

find_entry_points

경로 탐색 전에 좌표를 차량 진입로·택시 승하차 지점으로 보정합니다


##### TOOL

get_admin_boundary

시도·시군구·읍면동·리의 행정구역 경계를 가져옵니다


##### TOOL

find_route

경유지 최대 5개의 자동차 경로를 실시간 또는 출발·도착 시각 기준으로 탐색합니다


##### TOOL

find_walking_route

계단·엘리베이터 같은 시설 정보를 담은 도보·킥보드(PM) 경로를 탐색합니다


##### TOOL

optimize_waypoint_order

경유지 최대 10곳의 최적 방문 순서를 구합니다


##### TOOL

get_distance_matrix

여러 지점 사이의 거리·시간 행렬을 구합니다


##### TOOL

lookup_category_code

분류 이름으로 분류 코드를 찾습니다 (API를 호출하지 않습니다)


#### MAPACTIONS


#### 지도에서 할 수 있는 일

지도는 결과를 보여 주는 데서 끝나지 않습니다. 대화의 흐름이 끊기지 않도록 지도 안에서 옵션을 바꿔 도구를 다시 호출할 수 있습니다.


##### TABLEHEADER

결과

지도에서 하는 일


##### TABLEBODY

장소 검색

언어 바꾸기 · 페이지 넘기기 · 현재 지도에서 재검색 · 경로 만들기 프롬프트 생성

주변 분류 검색

페이지 넘기기 · 경로 만들기 프롬프트 생성

지오코딩

페이지 넘기기

자동차 경로

탐색 기준 변경(추천·무료 도로·고속도로) · 차종 변경

도보 경로

이동 수단 변경(도보·킥보드) · 탐색 기준 변경

거리·시간 행렬

실시간 교통 반영


##### TIP

모든 지도에서 지도 유형(일반·항공·하이브리드·지형)과 밝은·어두운 테마를 바꿀 수 있고, MCP Host가 지원하면 전체화면으로 볼 수 있습니다.


### USAGE


### 사용 예시

MCP 서버 설치 후, AI에게 다음과 같이 자연어로 요청하실 수 있습니다. 결과를 지도로 보고 싶다면 지도에 보여줘 를 함께 요청하세요. Claude Desktop 등 일부 MCP Host는 다른 지도 도구를 기본으로 사용할 수 있으니, 요청 끝에 INAVI MCP를 사용해줘 를 붙이는 것을 추천합니다. 실제 답변 내용은 제공되는 예시와 다를 수 있습니다.


#### EXAMPLES


##### ID

place-search


##### BADGE

장소 검색


##### USERQUERY

판교역 주변 스타벅스 찾아서 지도에 보여줘. INAVI MCP를 사용해줘


##### IMAGE

place


##### IMAGEALT

판교역 주변 스타벅스 검색 결과를 대화 안의 지도로 표시한 화면


##### ID

route-search


##### BADGE

경로 탐색


##### USERQUERY

판교역에서 강남역까지 이동 경로를 지도에 보여줘. INAVI MCP를 사용해줘.


##### IMAGE

route


##### IMAGEALT

판교역에서 강남역까지 자동차 경로를 대화 안의 지도로 표시한 화면


### PRICING


### 이용 요금

API MCP 서버는 INAVI Maps API를 직접 호출하므로 APPKEY가 반드시 필요합니다. MCP 서버 자체는 무료로 제공되며, API 사용량에 따른 요금은 별도로 적용됩니다. 요금에 대한 자세한 설명은 요금 소개 를 참고해 주세요.


### TROUBLESHOOTING


### 문제 해결

연동이 잘 안된다면 아래 항목을 체크해 보세요!


#### TIPS


#### MCP 서버가 연결되지 않아요.

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" 로 설정되어야 합니다.


#### 인증에 실패해요. (300)

INAVI_APPKEY 에 입력한 APPKEY 값이 올바른지 확인해 주세요.


#### 지도 대신 "지도 표시 없이 조회한 결과입니다."만 표시돼요.

정상 동작입니다. 결과를 지도로 보고 싶다면 요청에 지도에 보여줘 를 함께 붙여 주세요. 지도는 MCP Apps를 지원하는 MCP Host에서만 표시됩니다.


#### 지도가 빈 화면으로 보여요.

imaps.inavi.com 에 접근할 수 있는지 확인해 주세요. 사내망 방화벽 등으로 차단된 경우 지도가 표시되지 않습니다.


### SUPPORT


### 문의 및 지원

개발하시다 궁금한 점이 생기면 아래 채널로 편하게 연락 주세요.


#### CHANNELS


##### ID

mcp-technical-help


#### 기술적인 도움


##### CONTENT

MCP 서버 설정 및 연동 가이드


##### EMAIL

devbaek@inavi.kr


##### ID

mcp-service-inquiry


#### APPKEY 및 도입 문의


##### CONTENT

INAVI Maps 서비스 도입 및 계정 문의


##### EMAIL

impsbiz@inavi.kr


##### ID

mcp-developer-community


#### 개발 문의


##### CONTENT

개발자 커뮤니티 및 질문 게시판


##### LINKTEXT

INAVI Maps 개발문의 바로가기