iNavi

INAVI Maps Docs MCP 服务

为 AI 助手赋予地图智能的 MCP（Model Context Protocol）服务。

连接 INAVI Maps Docs MCP Server 后，AI 就能理解 INAVI Maps 的位置服务 API 和 Web JS SDK，并直接生成交互式地图。无需另外查阅文档或手动编写代码，只需通过自然语言对话，即可实现基于地图的功能。

• API 规范 - 为 AI 提供 30 多个 INAVI Maps API 规范（基于 OAS），涵盖地理编码、POI 搜索、路线规划、地图匹配等
• 地图 SDK 示例 - 使用 18 个可直接运行的地图 SDK 示例，创建包含标记、聚类、多边形、折线等元素的交互式地图
• SDK 参考 - 提供 Web JS SDK 的类、方法、选项和事件定义，让 AI 按照实际签名编写示例中未涵盖的功能

适合以下人群：

• 快速原型设计 - 无需阅读 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 或更高版本。

标准配置 — 可直接用于大多数 MCP 主机。

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

展开所用工具的说明，查看配置位置。

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

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

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

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

使用示例

安装 MCP 服务后，用自然语言向 AI 提出请求。

API 探索与代码生成

此 MCP 服务会向 AI 提供 INAVI Maps API 规范。AI 不会直接调用 API，而是参考 API 规范，为你编写正确的调用代码。

INAVI Maps에서 사용할 수 있는 지오코딩 관련 API를 알려줘

리버스 지오코딩 API의 요청/응답 명세를 보여줘

주소를 좌표로 변환하는 API 호출 코드를 TypeScript로 작성해줘

출발지-도착지 경로 탐색 API를 사용하는 예제 코드를 만들어줘

N:1 거리 매트릭스 API로 가장 가까운 매장을 찾는 로직을 구현해줘

地图可视化

AI 会先根据地图 SDK 示例搭建可运行的页面，再从 SDK 参考中确认示例未涵盖的选项、方法和事件，并将其应用到页面中。

INAVI Maps 지도에 마커를 표시하는 HTML 페이지를 만들어줘

여러 지점을 클러스터로 묶어서 지도에 표시하는 페이지를 만들어줘

경로를 교통 상황 색상으로 지도에 시각화하는 페이지를 만들어줘

서울 주요 관광지를 폴리곤 영역과 마커로 표시하는 지도를 만들어줘

클러스터에서 마커를 클릭하면 해당 장소의 정보를 InfoWindow로 보여줘

查询 SDK 参考

AI 会先确认 Web JS SDK 的类和方法定义、选项，而不是依靠记忆猜测，然后再作答。

Marker에서 사용할 수 있는 이벤트와 옵션을 알려줘

Map#fitBounds의 파라미터와 옵션을 알려줘

Polyline 선 스타일(LineStyle)로 지정할 수 있는 값을 정리해줘

组合使用

结合使用 API 规范、地图 SDK 示例和 SDK 参考，可以实现更复杂的功能。

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

경로 탐색 API 호출 결과를 지도 위에 폴리라인으로 그리고, 지도 범위를 경로 전체에 맞춰줘

可用工具

此 MCP 服务提供三类共 6 个工具。每对工具都设计为两步工作流：探索 → 详细查询。

API 规范工具

向 AI 提供 INAVI Maps API 规范（基于 OAS），让 AI 无需直接阅读 API 文档，也能编写正确的 API 调用代码。

工作流： 使用 list_api_specs 浏览可用 API，然后将 operationId 传递给 get_api_spec，查询参数、请求/响应架构等详细规范。

地图 SDK 示例工具

提供可直接运行的地图 SDK 示例（HTML），涵盖 SDK 加载器和地图初始化。AI 可自定义示例中的数据值（坐标、标签等），生成定制化地图页面。

工作流： 使用 list_map_examples 浏览可用示例，然后将 id 传递给 get_map_example，查询完整的 HTML 代码。

SDK 参考工具

提供 INAVI Maps Web JS SDK 的类以及选项/类型定义。对于地图 SDK 示例中未涵盖的选项、方法和事件，AI 无需凭记忆猜测，而是可以先确认实际签名再编写代码。

工作流： 创建地图时，先使用 list_map_examples 获取可运行的地图 SDK 示例；若需要示例中未包含的功能，则使用 list_sdk_docs → get_sdk_doc 确认准确签名。SDK 加载器脚本仅包含在示例中，因此仅凭参考资料无法创建可运行的页面。

docId 可接受类/类型 ID（inavi.maps.Map、MapOptions）和方法长名称（inavi.maps.Map#fitBounds）。

工具

共提供 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

解决方法：

• 更新到最新版本（此问题已修复）
• 本地开发时使用 MCP Logging 代替 console.log（避免污染 stdout）

如需了解更详细的故障排除方法，请参阅 Troubleshooting Guide。

문서

라이선스

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

참고 자료

• Model Context Protocol - MCP 공식 문서
• Claude Desktop - Claude Desktop 다운로드
• INAVI Maps API - INAVI Maps API 공식 문서