# 서버 연동 가이드

INAVI Maps는 효율적인 개발 환경을 위해 MCP(Model Context Protocol) 기반 AI 도구를 지원합니다. 본 가이드는 LLM과 연동된 도구를 활용하여 코드 작성, 환경 설정 등 연동 전 과정의 생산성을 높이는 방법을 안내합니다.

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

### BANNER


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

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


#### BUTTONTEXT

Markdown 복사


### SETUP


### 환경 설정

사용 중인 AI 도구에서 INAVI Maps MCP 서버를 연결해 보세요. 아래 서버 설정을 각 도구의 서버 설정 경로에 추가하면 됩니다. (Codex는 JSON이 아닌 TOML 형식이라 변환이 필요해요.)


#### GITHUBURL

https://github.com/inavi-systems/inavi-mcp


#### 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-mcp": { "command": "npx", "args": ["-y", "@inavi-maps/mcp-server"] } } }


##### GUIDEURL

https://cursor.com/docs/mcp


##### KEY

claude-code


##### TOOL

* Claude Code


##### PATH

~/.claude.json


##### CONFIGTYPE

json


##### CODE

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


##### 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-mcp": { "command": "npx", "args": ["-y", "@inavi-maps/mcp-server"] } } }


##### 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-mcp": { "command": "npx", "args": ["-y", "@inavi-maps/mcp-server"] } } }


##### GUIDEURL

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


##### KEY

vscode


##### TOOL

VS Code


##### PATH

사용자 프로필


##### CONFIGTYPE

json


##### CODE

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


##### 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-mcp] command = "npx" args = ["-y", "@inavi-maps/mcp-server"]


##### GUIDEURL

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


#### CLINOTETITLE

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


#### CLICOMMANDS


##### TOOL

Claude Code


##### COMMAND

claude mcp add --transport stdio inavi-maps-mcp -- npx -y @inavi-maps/mcp-server


##### TOOL

Codex


##### COMMAND

codex mcp add inavi-maps-mcp -- npx -y @inavi-maps/mcp-server


### TOOLS


### 사용 가능한 도구

INAVI Maps MCP 서버는 총 4개의 도구를 제공합니다. 각 도구 쌍은 목록 조회 → 상세 조회의 2단계 워크플로우로 설계되어 있습니다


#### TOOLPAIRS


##### TOOL

list_map_examples

WEB (JS) 지도 예제 목록을 조회합니다


##### CATEGORY

dynamic-maps, marker, shapes, infowindow


##### PARAMETER

category, limit, offset


##### TOOL

get_map_example

특정 예제의 HTML 코드와 의존성 정보를 반환합니다


##### CATEGORY

html, dependencies


##### PARAMETER

exampleId


##### TOOL

list_api_specs

API 목록을 조회합니다


##### CATEGORY

search-place, search-geocoding, route-directions ...


##### PARAMETER

category, limit, offset


##### TOOL

get_api_spec

API 상세 스펙을 반환합니다


##### CATEGORY

요청/응답 스키마 상세


##### PARAMETER

specId


### USAGE


### 사용 예시

MCP 서버 설치 후, AI에게 다음과 같이 자연어로 요청하실 수 있습니다. 실제 답변 내용은 제공되는 예시와 다를 수 있습니다.


#### EXAMPLES


##### ID

code-generation


##### BADGE

코드 생성


##### USERQUERY

아이나비 API를 활용해서 주소를 좌표로 변환하는 TypeScript 코드를 작성해 줘

아래 코드는 INAVI Maps MCP /maps/v3.0/appkeys/{APPKEY}/coordinates API를 사용하여 주소를 좌표로 변환하는 예시입니다.


##### CODE

const APPKEY = 'YOUR_APPKEY'; // GET /maps/v3.0/appkeys/{APPKEY}/coordinates url.searchParams.set('query', address); url.searchParams.set('coordtype', '1'); // WGS84 const res = await fetch(url); const data = await res.json(); const { posx, posy } = data.address.adm[0]; return { lat: Number(posy), lng: Number(posx) };


##### POINTS


##### API


###### CONTENT

GET) /maps/v3.0/appkeys/{APPKEY}/coordinates


##### 필수 쿼리


###### CONTENT

query


##### 좌표계


###### CONTENT

coordtype=1 → WGS84


##### 응답


###### CONTENT

address.adm[0].posx = 경도, posy = 위도


##### ID

api-search


##### BADGE

API 탐색


##### USERQUERY

아이나비 다국어 통합 검색 API의 요청/응답 스펙을 보여줘

다국어 통합 검색 API(g-searches)의 요청 스펙입니다. GET 방식으로 검색어와 언어 코드를 필수와 받으며, 공간 검색과 반경 검색을 지원합니다.


##### CODE

// 필수 파라미터 query: string // 검색 키워드 lang: string // ko, en, ja, zh // 주요 선택 파라미터 coordtype: number // 좌표계 (0: TW, 1: WGS84) spopt: number // 공간 검색 (0: 전체, 1: 공간, 2: 반경) radius: number // 검색 반경 (m)


##### METHODS


##### 메서드


###### CONTENT

GET


##### 운영ID


###### CONTENT

getGlobalSearchesResult


##### ID

map-visualization


##### BADGE

지도 시각화


##### USERQUERY

서울 주요 관광지를 아이나비 지도에 폴리곤 영역과 마커로 표시해서 만들어줘

아래 HTML을 파일로 저장한 뒤 {APPKEY}를 실제 아이나비 APPKEY로 교체하면 서울 주요 관광지 지도를 바로 확인할 수 있습니다.


##### CODE

// 서울 주요 관광지 · 폴리곤 + 마커 지도 const map = new inavi.maps.Map({ center: [126.9780, 37.5650], zoom: 12 }); // 폴리곤: 경복궁, 인사동, 홍대, 명동 new inavi.maps.Polygon({ map, path, style }); // 마커: 경복궁, 북촌한옥마을, 인사동, 명동, N서울타워, 홍대 new inavi.maps.Marker({ map, position });


##### ID

complex-usage


##### BADGE

복합 활용


##### USERQUERY

지오코딩 API로 주소를 좌표로 변환하고, 그 결과를 아이나비 지도에 마커로 표시해서 만들어줘

주소를 지오코딩해서 좌표를 얻은 뒤, 아이나비 지도에 마커로 표시하는 HTML 예제입니다. {APPKEY}를 실제 APPKEY로 교체하세요.


##### CODE

// Step 1: 주소 → 좌표 (Geocoding API) GET /maps/v3.0/appkeys/{APPKEY}/coordinates ?query=강남구 테헤란로 231&coordtype=1 // Step 2: 좌표 → 지도 마커 (Maps JS API) const { posx, posy } = data.address.adm[0]; new inavi.maps.Marker({ map, position: [posx, posy] });


### PRICING


### 이용 요금

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


### TROUBLESHOOTING


### 문제 해결

연동이 잘 안된다면 아래 세 가지만 체크해 보세요!


#### TIPS


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

npx 명령어가 설치되어 있는지, Node.js 22 이상인지 확인하세요. 터미널에서 node -v 명령어로 버전을 확인하실 수 있습니다.


#### 설정 파일 경로에 파일이나 폴더가 없어요

해당 경로에 폴더나 파일이 존재하지 않는 경우, 직접 해당 폴더 및 .json (또는 .toml ) 파일을 생성하여 설정을 작성하시면 정상적으로 인식됩니다.


#### 도구별로 설정 형식이 달라서 오류가 발생해요

사용 중인 AI 도구에 맞는 작성 형식(JSON / TOML) 및 키 이름을 확인해 주세요. Codex: JSON이 아닌 TOML 형식 [mcp_servers.inavi-maps-mcp] 으로 작성해야 합니다. VS Code: 최상위 키 이름이 "mcpServers" 가 아닌 "servers" 로 설정되어야 합니다.


### 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 개발문의 바로가기