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

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