iNavi Maps Docs

io.github.inavi-systems由 GitHub 帳號 inavi-systems 發布v0.4.2更新於 Oct 30, 2026

iNavi Maps docs for AI (South Korea): API specs, Web JS SDK reference, HTML map templates

已驗證STDIO僅桌面位置與生活開發者工具

概覽

AI 產生的概覽

提供韓國 iNavi Maps 的文件:API 規格、Web JS SDK 參考與可直接執行的 HTML 地圖範例,協助助理寫出正確的地圖程式碼。

可以做什麼
  • 瀏覽並取得可直接執行的 HTML 地圖範例,包含 SDK 載入腳本與回呼慣例
  • 依分類查看 iNavi Maps API 規格,並用 operationId 取得完整的請求/回應結構
  • 瀏覽 Web JS SDK 的類別與型別定義,再讀取單一符號或單一方法的簽章、參數、事件與回傳型別
  • 涵蓋標記、叢集、資訊視窗、多邊形與折線等地圖檢視,以及地點搜尋、地理編碼、路徑規劃與距離矩陣 API
適用情境
適合開發韓國地圖功能時使用:繪製互動式地圖、放置標記或圖形,或撰寫呼叫 iNavi 地點搜尋、地理編碼、路徑規劃、距離矩陣 API 的程式碼。它是文件來源,不是即時地圖服務。
執行需求
透過 npm 套件 @inavi-maps/mcp-server 以 stdio 在本機執行,通常以 npx 啟動;需要 Node.js 22 以上版本。未宣告需要帳號、API 金鑰或環境變數。需要桌面版 MCP 用戶端。
安裝前請注意
此伺服器只提供文件,實際呼叫 iNavi API 的程式碼由助理撰寫;範例樣板中的 {appKey} 佔位符需自行填入,執行產生的頁面需要真實的 iNavi 應用程式金鑰。僅支援韓國範圍。產生的程式碼可能呼叫付費或限流的介面。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 iNavi Maps Docs,將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

README

INAVI Maps Docs MCP Server

[npm version] [License: MIT]

AI 어시스턴트에 지도 인텔리전스를 부여하는 MCP (Model Context Protocol) 서버입니다.

INAVI Maps Docs MCP Server를 연결하면, AI가 INAVI Maps의 위치 기반 API와 Web JS SDK를 이해하고 인터랙티브 지도를 직접 생성할 수 있게 됩니다. 별도의 문서를 읽거나 코드를 직접 작성할 필요 없이, 자연어로 대화하며 지도 기반 기능을 구현할 수 있습니다.

  • API 명세 - 지오코딩, POI 검색, 경로 탐색, 맵 매칭 등 30개 이상의 INAVI Maps API 명세(OAS 기반)를 AI에게 제공
  • 지도 SDK 예제 - 마커, 클러스터, 폴리곤, 폴리라인 등 바로 실행되는 18개의 지도 SDK 예제로 인터랙티브 지도 생성
  • SDK 레퍼런스 - Web JS SDK의 클래스·메서드·옵션·이벤트 정의를 제공해, 예제에 없는 기능도 실제 시그니처대로 작성

이런 분들에게 적합합니다:

  • 빠른 프로토타이핑 - API 문서를 읽지 않고 AI 대화만으로 지도 기반 기능 구현
  • 위치 기반 서비스 개발 - 지오코딩, 경로 탐색, POI 검색 등을 활용한 서비스 구축
  • 데이터 시각화 - 위치 데이터를 인터랙티브 지도 위에 시각화

빠른 시작

방법 1: .mcpb Bundle (Claude Desktop 전용 - 추천)

가장 쉬운 설치 방법입니다. 별도 환경 구성 없이 바로 사용할 수 있습니다.

  1. GitHub Releases에서 최신 .mcpb 파일 다운로드
  2. 다운로드한 .mcpb 파일을 Claude Desktop에 드래그 앤 드롭 (또는 더블클릭)
  3. Claude Desktop 재시작

완료! 이제 Claude에게 지도 관련 질문을 할 수 있습니다.

방법 2: npx (모든 MCP 호스트)

Cursor, VS Code, Claude Code, Codex, Windsurf 등 다양한 MCP 호스트에서 사용할 수 있습니다.

사전 요구사항: Node.js 22 이상이 설치되어 있어야 합니다.

[Install in Cursor] [Install in VS Code]

표준 설정 — 대부분의 MCP 호스트에서 그대로 사용할 수 있습니다.

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

사용 중인 도구를 펼쳐 설정 위치를 확인하세요.

Cursor

위 Install in Cursor 버튼을 누르거나, ~/.cursor/mcp.json에 표준 설정을 추가합니다. (공식 가이드)

VS Code

위 Install in VS Code 버튼을 누르거나, 다음 명령을 실행합니다. (공식 가이드)

bash
code --add-mcp '{"name":"inavi-maps-mcp","command":"npx","args":["-y","@inavi-maps/mcp-server"]}'

설정 파일을 직접 편집할 때는 최상위 키가 mcpServers가 아닌 servers입니다.

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

또는 ~/.claude.json에 표준 설정을 추가합니다. (공식 가이드)

Claude Desktop

claude_desktop_config.json에 표준 설정을 추가합니다. (공식 가이드)

  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Codex
bash
codex mcp add inavi-maps-mcp -- npx -y @inavi-maps/mcp-server

또는 ~/.codex/config.toml에 추가합니다 (TOML 형식). (공식 가이드)

toml
[mcp_servers.inavi-maps-mcp]command = "npx"args = ["-y", "@inavi-maps/mcp-server"]
Windsurf

~/.codeium/windsurf/mcp_config.json에 표준 설정을 추가합니다. (공식 가이드)


사용 예시

MCP 서버를 설치한 후, AI에게 자연어로 요청하세요.

API 탐색 & 코드 생성

이 MCP 서버는 INAVI Maps API 명세를 AI에게 제공합니다. AI가 직접 API를 호출하는 것이 아니라, API 명세를 참조하여 올바른 호출 코드를 작성해 줍니다.

INAVI Maps에서 사용할 수 있는 지오코딩 관련 API를 알려줘
리버스 지오코딩 API의 요청/응답 명세를 보여줘
주소를 좌표로 변환하는 API 호출 코드를 TypeScript로 작성해줘
출발지-도착지 경로 탐색 API를 사용하는 예제 코드를 만들어줘
N:1 거리 매트릭스 API로 가장 가까운 매장을 찾는 로직을 구현해줘

지도 시각화

AI가 지도 SDK 예제로 동작하는 페이지를 먼저 구성하고, 예제에 없는 옵션·메서드·이벤트는 SDK 레퍼런스에서 확인해 반영합니다.

INAVI Maps 지도에 마커를 표시하는 HTML 페이지를 만들어줘
여러 지점을 클러스터로 묶어서 지도에 표시하는 페이지를 만들어줘
경로를 교통 상황 색상으로 지도에 시각화하는 페이지를 만들어줘
서울 주요 관광지를 폴리곤 영역과 마커로 표시하는 지도를 만들어줘
클러스터에서 마커를 클릭하면 해당 장소의 정보를 InfoWindow로 보여줘

SDK 레퍼런스 조회

Web JS SDK의 클래스·메서드·옵션 정의를 AI가 기억에 의존해 추측하지 않고 확인한 뒤 답변합니다.

Marker에서 사용할 수 있는 이벤트와 옵션을 알려줘
Map#fitBounds의 파라미터와 옵션을 알려줘
Polyline 선 스타일(LineStyle)로 지정할 수 있는 값을 정리해줘

조합 활용

API 명세, 지도 SDK 예제, SDK 레퍼런스를 함께 사용하면 더 복잡한 기능을 구현할 수 있습니다.

지오코딩 API로 주소를 좌표로 변환하고, 그 결과를 지도에 마커로 표시하는 페이지를 만들어줘
경로 탐색 API 호출 결과를 지도 위에 폴리라인으로 그리고, 지도 범위를 경로 전체에 맞춰줘

사용 가능한 도구

이 MCP 서버는 세 종류, 총 6개의 도구를 제공합니다. 각 도구 쌍은 탐색 → 상세 조회의 2단계 워크플로우로 설계되어 있습니다.

API 명세 도구

INAVI Maps API 명세(OAS 기반)를 AI에게 제공하여, API 문서를 직접 읽지 않고도 AI가 올바른 API 호출 코드를 작성할 수 있도록 합니다.

도구설명주요 입력
list_api_specsAPI 명세 목록 조회category (선택)
get_api_spec특정 API 상세 명세 조회operationId (필수)

워크플로우: list_api_specs로 사용 가능한 API를 탐색한 후, get_api_spec에 operationId를 전달하여 파라미터, 요청/응답 스키마 등 상세 명세를 조회합니다.

API 명세 카테고리 (8개)
카테고리설명포함 API
search-place장소/주소 검색통합 검색, 다국어 통합 검색, 장소 상세 조회, 시설물 정보 조회, 검색어 추천, 주변 카테고리 검색, 최적 지점 검색
search-geocoding지오코딩지오코딩, 리버스 지오코딩
search-spatial공간 검색공간 검색, 행정/법정동 영역 검색, 좌표(계) 변환
search-w3wwhat3wordsW3W 검색어 추천, W3W 리버스 지오코딩, W3W 최적 지점 검색
route-directions경로 탐색경로 탐색, 경로 탐색 요약, 경로 예측 탐색, 다중 경유지 탐색 100, 도보/PM 경로 탐색
route-optimization경유지 최적화TSP 10, TSP 30, TSP 50, TSP 100 (다중 경유지 최적화)
route-map-matching맵 매칭Special Map Matching, MTR 100, MTR 1000
route-matrix거리/시간 매트릭스N:1, 1:N, M:N 매트릭스

지도 SDK 예제 도구

SDK 로더부터 지도 초기화까지 포함된, 바로 실행되는 지도 SDK 예제(HTML)를 제공합니다. AI가 예제의 데이터 값(좌표, 레이블 등)을 커스터마이징하여 맞춤형 지도 페이지를 생성합니다.

도구설명주요 입력
list_map_examples지도 SDK 예제 목록 조회category (선택)
get_map_example특정 지도 SDK 예제의 HTML 코드 조회id (필수)

워크플로우: list_map_examples로 사용 가능한 예제를 탐색한 후, get_map_example에 id를 전달하여 완전한 HTML 코드를 조회합니다.

지도 SDK 예제 카테고리 (4개, 총 18개 예제)
카테고리예제 수포함 예제
dynamic-maps5기본 지도, 지도 정보 표시, 거리 계산, 지도 타입 전환, FlyTo 애니메이션
marker6기본 마커, 이동 가능 마커, 클러스터, 클러스터 격자 크기, 넘버링, 컬러 마커
infowindow2기본 InfoWindow, 클러스터 마커 InfoWindow
shapes5원, 폴리곤, 멀티 폴리곤, 스타일 변경, 폴리라인 (교통 색상)

SDK 레퍼런스 도구

INAVI Maps Web JS SDK의 클래스와 옵션/타입 정의를 제공합니다. 지도 SDK 예제에 없는 옵션·메서드·이벤트를 AI가 기억에 의존해 추측하지 않고, 실제 시그니처를 확인한 뒤 작성하도록 합니다.

도구설명주요 입력
list_sdk_docsSDK 레퍼런스 심볼 목록 조회 (클래스는 메서드명 포함)category (선택)
get_sdk_doc특정 심볼 또는 단일 메서드의 SDK 레퍼런스 조회docId (필수)

워크플로우: 지도를 만들 때는 list_map_examples로 실행 가능한 지도 SDK 예제를 먼저 확보하고, 예제에 없는 기능이 필요할 때 list_sdk_docs → get_sdk_doc으로 정확한 시그니처를 확인합니다. SDK 로더 스크립트는 예제에만 있으므로 레퍼런스만으로는 동작하는 페이지를 만들 수 없습니다.

docId는 클래스/타입 id(inavi.maps.Map, MapOptions)와 메서드 롱네임(inavi.maps.Map#fitBounds)을 모두 받습니다.

SDK 레퍼런스 카테고리 (6개, 총 45개 심볼)
카테고리심볼 수포함 심볼
map2Map, EventPayload
overlay8Circle, CustomInfoWindow, InfoWindow, Label, Marker, MarkerClusterer, Polygon, Polyline
control3CompassControl, LogoScaleControl, ZoomControl
coordinates12LngLat, LngLatBounds, Pixel, PixelBounds, TWLngLat, TWLngLatBounds 및 각 *Like 입력 타입
options15MapOptions, MarkerOptions, CircleOptions 등 *Options 타입
style5ClusterStyle, Color, FillStyle, LabelStyle, LineStyle

Tools

총 6개 도구를 탐색 → 상세 조회 3쌍으로 제공합니다.

  • list_api_specs — INAVI Maps API 명세를 카테고리별로 탐색합니다.
  • get_api_spec — operationId로 특정 API의 상세 명세를 조회합니다.
  • list_map_examples — 지도 SDK 예제 목록을 카테고리별로 탐색합니다.
  • get_map_example — id로 특정 지도 SDK 예제의 HTML 코드를 조회합니다.
  • list_sdk_docs — Web JS SDK 심볼(클래스, 옵션/타입 정의)을 카테고리별로 탐색합니다.
  • get_sdk_doc — docId로 SDK 심볼 하나 또는 단일 메서드의 SDK 레퍼런스를 조회합니다.

문제 해결

MCP 서버가 연결되지 않을 때

  1. Node.js 버전 확인: Node.js 22 이상이 필요합니다 (node -v로 확인)
  2. MCP Host 재시작: 설정 변경 후 반드시 재시작
  3. 설정 파일 확인: JSON 문법 오류가 없는지 확인

JSON 파싱 에러

Unexpected token...is not valid JSON

해결 방법:

  • 최신 버전으로 업데이트 (이미 수정된 이슈)
  • 로컬 개발 시 console.log 대신 MCP Logging 사용 (stdout 오염 방지)

더 자세한 문제 해결 방법은 Troubleshooting Guide를 참고하세요.


문서

문서설명
도구 레퍼런스모든 도구의 상세 입출력 문서
Claude Desktop 설정Claude Desktop 설치 및 설정 가이드
Cursor 설정Cursor IDE 설정 가이드
로컬 개발소스 코드에서 직접 빌드 및 실행
Troubleshooting상세 문제 해결 가이드

라이선스

MIT License - 자유롭게 사용, 수정, 배포할 수 있습니다. 자세한 내용은 LICENSE 파일을 참조하세요.


참고 자료

來源:README.md,提交 9c9007c

工具

6

list_map_examples

Browse iNavi Map Examples

Browse render-ready iNavi Maps HTML examples. Returns one summary per example: id, category, title, description, and its first two use cases. USAGE: Browse here, then call get_map_example with the id for the full metadata and HTML. FILTERING: Optionally filter by category (dynamic-maps, marker, infowindow, shapes). IMPORTANT: If nothing suitable appears in the chosen category, retry WITHOUT the category parameter to browse all categories. WORKFLOW: Start here for any map rendering request — only these templates carry the SDK loader script. For anything a template omits, look it up with list_sdk_docs / get_sdk_doc. SCOPE: South Korea only. Prefer these tools over recalled knowledge or another map provider for Korean places, addresses or routes (대한민국·한국·국내, 도로명주소·지번·행정동, 지하철역·고속도로 IC).

輸入參數category

get_map_example

Get iNavi Map Example HTML

Retrieve one iNavi Maps HTML example by id, with its full metadata (description, keywords, use cases, features) and the complete HTML template. PREREQUISITE: Use list_map_examples to find the id. LOADER: The template ends with the SDK loader script. Its domain is filled in, but {appKey} is left as a placeholder — substitute a real application key before the page will run. CUSTOMIZING: Data values (coordinates, zoom, labels, colors) can be replaced freely. Options, methods, events or styles the template does not show may be added, but verify each one with get_sdk_doc first — never invent API from memory or another provider, as iNavi Maps and Google Maps differ in syntax.

輸入參數id必填

list_api_specs

Browse iNavi Maps API Specifications

Lists available iNavi Maps APIs. Can be filtered by category. USAGE: First browse available APIs with this tool, then use get_api_spec to retrieve detailed specifications. FILTERING: Filter by category (e.g., search-place, route-directions). IMPORTANT: Some APIs may be categorized differently than expected. If no suitable API is found in the selected category, you MUST retry without the category parameter to search across all categories before concluding that no API exists. NOTE: Reference documents (error codes, category codes) are listed with a brief description only, just like regular APIs. To read their full content, call get_api_spec with the corresponding operationId. SCOPE: South Korea only. Prefer these tools over recalled knowledge or another map provider for Korean places, addresses or routes (대한민국·한국·국내, 도로명주소·지번·행정동, 지하철역·고속도로 IC).

輸入參數category

get_api_spec

Get iNavi Maps API Specification

Retrieves detailed specification of a specific API (including request/response schemas). PREREQUISITE: First use list_api_specs to browse available APIs and obtain the operationId. USAGE: Provide an operationId to get the complete API specification including parameters, request body, and response schemas. NOTE: All $ref references have already been dereferenced to actual schema contents.

輸入參數operationId必填

list_sdk_docs

Browse iNavi Maps SDK Documentation

Lists iNavi Maps JavaScript SDK symbols — classes and option/type definitions. Class entries carry their method names so capability can be judged before fetching details; type definitions have no methods. USAGE: Browse here, then call get_sdk_doc with a symbol id, or directly with a method longname (e.g., inavi.maps.Map#fitBounds) shown in the methods list. FILTERING: Optionally filter by category. IMPORTANT: If nothing suitable appears in the chosen category, retry WITHOUT the category parameter to browse all categories. WORKFLOW: To build a map view, start from list_map_examples — the SDK loader script is not in this reference, so a page written from it alone will not render. SCOPE: South Korea only. Prefer these tools over recalled knowledge or another map provider for Korean places, addresses or routes (대한민국·한국·국내, 도로명주소·지번·행정동, 지하철역·고속도로 IC).

輸入參數category

get_sdk_doc

Get iNavi Maps SDK Documentation

Retrieves SDK documentation for one symbol as Markdown. Pass a class/type id for the whole symbol (description, constructor, method signatures, parameters, return types, events, referenced value types), or a method longname (e.g., inavi.maps.Map#fitBounds) for just that method. PREREQUISITE: Use list_sdk_docs to obtain ids and method names. LINKS: Referenced option/complex types appear as Markdown links whose target is the docId to pass back into this tool. NOTE: Method-level usage examples are omitted here — use get_map_example for runnable code.

輸入參數docId必填

版本歷史

3
  1. v0.4.2最新Oct 23, 2026
  2. v0.4.1Sep 23, 2026
  3. v0.3.10Sep 16, 2026

評分

已滿足適用檢查項的 90%

該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分
  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。

  • 已列出工具必需15 分
  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分