mcpField
I
INAVI Maps API

INAVI Maps API

本地服务
mapsapi.inavisys.com地图与出行06 天前更新
代码仓库访问官网

关于 INAVI Maps API

这是供 AI 助手调用 INAVI Maps API 的 MCP 服务，侧重在韩国查找地点、地址和路线。它还可通过 MCP Apps 在对话中呈现交互式地图。

主要功能

  1. 01地点及周边分类搜索
  2. 02地址地理编码与反向地理编码
  3. 03汽车、步行和滑板车路线
  4. 04途经点排序与距离矩阵
  5. 05在兼容的宿主中显示交互地图

适用场景

  1. 01查找附近商家和服务
  2. 02转换地址与坐标
  3. 03比较路线方案和行程时间
  4. 04在地图上查看搜索结果和路线

MCP 相关

向 MCP 客户端提供 11 个 INAVI Maps API 工具，包括搜索、地理编码和路线查询。MCP Apps 可在支持它的宿主中将结果显示为交互式地图。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置
{
  "mcpServers": {
    "inavi-systems-inavi-api": {
      "command": "npx",
      "args": [
        "-y",
        "@inavi-maps/api-mcp-server"
      ],
      "env": {
        "INAVI_APPKEY": "<INAVI_APPKEY>"
      }
    }
  }
}
启动命令npx -y @inavi-maps/api-mcp-server
需要配置的环境变量
INAVI_APPKEY密钥INAVI Maps API Key

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包
npm@inavi-maps/api-mcp-server0.0.4

工具

12

收录的工具列表 · 更新于 5 天前

参数类型必填说明
x1number否经度。bbox：左上；radius：中心；两者都不适用：距离参考点
x2number否右下角的经度，适用于 area="bbox"
y1number否纬度。bbox：左上；radius：中心；两者都不适用：距离参考点
y2number否area="bbox" 时右下角的纬度
areaenum否限制搜索区域的方式。省略此项则搜索全国。"bbox" 需要 x1/y1（左上）和 x2/y2（右下）；"radius" 需要 x1/y1 和 radius。bbox | radius
sortenum否结果排序。"recommended"（默认）、"name" 或 "distance"。只有在提供参考点（x1/y1）时，"distance" 才有意义。recommended | name | distance
querystring是搜索关键词。商家名称、建筑物名称、类别名称、地块地址或道路地址，或电话号码（例如 "판교역 카페" 或 "Pangyo Station"）。
radiusnumber否搜索半径，单位为米，适用于 area="radius"。注意：它只缩小 `poi` 的搜索范围；地址匹配项（`adm`）完全不受影响。
admcodestring否按行政区代码缩小结果范围
showMapboolean否是否在对话地图上呈现此结果（默认 false）。重要：中间查询时请保持关闭，例如获取坐标以用于路线规划或缩小候选范围。仅在展示给用户的单个结果上设为 true，否则对话中会堆积地图。
catecodestring否按类别代码缩小结果范围。使用 lookup_category_code 查找代码。
languageenum否结果语言（默认 "ko"）。重要：设置为 "ko" 以外的值时，会使用单独的 API，其结果不包含行政洞代码、洞级地址和关联网站信息。只有用户要求使用该语言返回结果时才设置此项。关键词本身仍可为韩语。ko | en | ja | zh
reqcountinteger否请求的结果数量（默认 20）。响应中的 totalcount 表示总数。
startpositioninteger否第一个结果的偏移量，从 0 开始。用于分页浏览结果。

详细介绍

INAVI 地图 API MCP 服务

npm version License: MIT

这是一个 MCP（Model Context Protocol）服务，可让 AI 助手直接调用 INAVI Maps API 来查找地点、地址和路线，并在 对话中的动态地图上显示结果。

  • 地点与地址搜索 - 支持按商户名称、行业和地址查找，搜索周边分类，以及地理编码和反向地理编码。
  • 路线 - 支持汽车（实时路线与出发时间预测）、步行和滑板车路线、途经点顺序优化，以及距离和时间矩阵。
  • 地图显示 - 通过 MCP Apps 在对话中显示结果，并支持多种交互。

获取 API Key

请在此处查看如何获取 API Key。

此服务必须使用 API Key 才能启动。 请在下方快速开始配置中的 INAVI_APPKEY 填入获取的密钥。

快速开始

可在 Claude Desktop、Cursor、VS Code、Claude Code、Codex、Windsurf 等多种 MCP 主机中使用。

前提条件： 必须安装 Node.js 22 或更高版本（使用 node -v 确认）。

Install in Cursor Install in VS Code

标准配置 — 大多数 MCP 主机都可以直接使用。将 YOUR_API_KEY 替换为获取的 API Key，然后 重启主机。

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

展开所用工具的部分，查看配置位置。

Claude Desktop

在 claude_desktop_config.json 中添加标准配置。(官方指南)

  • Windows：%APPDATA%\Claude\claude_desktop_config.json
  • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Cursor

点击上方的 Install in Cursor 按钮，或在 ~/.cursor/mcp.json 中添加标准配置。(官方指南) 如果通过按钮安装，请将配置中的 YOUR_API_KEY 替换为获取的 API Key。

VS Code

点击上方的 Install in VS Code 按钮，安装时会弹出窗口供你输入 API Key。密钥不会以明文形式保存在配置文件中。 或者，运行以下命令。(官方指南)

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

直接编辑配置文件时，顶层键应为 servers，而不是 mcpServers。

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

或者，在 ~/.claude.json 中添加标准配置。(官方指南)

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

或者，添加到 ~/.codex/config.toml 中（TOML 格式）。(官方指南)

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

在 ~/.codeium/windsurf/mcp_config.json 中添加标准配置。(官方指南)

只有支持 MCP Apps 的主机才能显示地图。 已在 Claude Desktop 中验证。 在不支持的主机中，工具调用和响应仍可正常工作，只是不会绘制地图。

使用示例

如果希望将结果可视化为地图，请一并提出“显示在地图上”。

Claude Desktop 和 ChatGPT App 内置支持 Google 地图。建议在提示词末尾加上 INAVI MCP를 사용해줘。

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

판교역 반경 500m 안의 편의점 전부 지도에 보여줘. INAVI MCP를 사용해줘

경기도 성남시 분당구 판교역로 240 좌표 알려줘. INAVI MCP를 사용해줘

127.110750, 37.402159 여기 주소가 어디야? INAVI MCP를 사용해줘
路线
판교역에서 강남역까지 자동차 경로 알려줘. 지도에 보여줘. INAVI MCP를 사용해줘

내일 아침 8시에 판교역에서 강남역으로 출발하면 얼마나 걸려? 8시 반이랑 비교해줘. INAVI MCP를 사용해줘

판교역에서 판교테크노밸리까지 걸어가는 길 알려줘. 계단은 피하고 싶어. INAVI MCP를 사용해줘

판교역에서 출발해서 서현역, 정자역, 미금역을 들르는 가장 짧은 순서 알려줘. INAVI MCP를 사용해줘

판교역, 서현역, 정자역 사이 거리랑 시간 비교해줘. INAVI MCP를 사용해줘

可用工具

提供 11 个工具，用于调用 INAVI Maps API。除了 lookup_category_code 之外的 10 个工具都可以绘制地图。

工具说明
search_places按商户名称、建筑名称、行业、地址或电话号码搜索地点和地址。支持韩语、英语、日语和中文
search_nearby_category查找某个地点周围（半径或矩形区域内）所有同类别的地点——例如名称各不相同的便利店、停车场和充电站
geocode_address将地址转换为坐标
reverse_geocode将坐标转换为地址、行政区代码和最近的建筑名称
find_entry_points路线规划前，将坐标校正为车辆入口、出租车上下车点
get_admin_boundary获取市道、市郡区、邑面洞和里的行政区边界
find_route最多包含 5 个途经点的汽车路线。支持实时路线，或基于出发、到达时间的预测路线
find_walking_route步行、滑板车（PM）路线。包含楼梯、电梯等设施信息
optimize_waypoint_order求出最多 10 个途经点的最佳访问顺序
get_distance_matrix求出多个地点之间的距离和时间矩阵
lookup_category_code按类别名称查找类别代码（不调用 API）
可以在地图上进行的操作

地图不只是展示结果。你可以更改选项值，在 MCP Apps 中调用工具，让对话流程保持连贯。

结果在地图上的操作
地点搜索更改语言 · 翻页 · 在当前地图中重新搜索 · 生成路线规划提示词
附近类别搜索翻页 · 生成路线规划提示词
地理编码翻页
汽车路线更改规划方式（推荐、免费道路、高速公路）· 更改车型
步行路线更改出行方式（步行、滑板车）· 更改规划方式
距离和时间矩阵纳入实时交通状况

路线规划会让你从列表或地图中选择出发地和目的地，然后将路线规划问题填入对话输入框。 发送前可以检查内容。列表中的对话按钮也会以相同方式将该地点传入对话。

所有地图都可以更改地图类型（普通、卫星、混合、地形）以及浅色、深色主题；如果 MCP 主机支持，还可以全屏查看。

环境变量

变量必需说明
INAVI_APPKEY必需INAVI Maps API Key

故障排除

MCP 服务无法连接时
  1. 确认 API Key：检查服务器设置的 env 中是否存在 INAVI_APPKEY——如果没有，服务器将无法启动
  2. 确认 Node.js 版本：需要 Node.js 22 或更高版本（使用 node -v 确认）
  3. 检查配置文件：确认没有 JSON 语法错误
  4. 重启 MCP Host：更改设置后，务必完全退出并重新启动
其他症状
症状检查项
认证失败（300）INAVI_APPKEY 的值是否正确
只显示“查询结果未显示在地图上。”，而不是地图这是正常现象。请在请求中添加“显示在地图上”
地图为空白是否可以访问 imaps.inavi.com（公司网络防火墙）
MCP Inspector 中看不到地图背景Inspector 会拦截地图 SDK 使用的 worker。请用它确认工具调用，并在 Claude Desktop 中查看地图

许可证

MIT License - 可自由使用、修改和分发。详情请参阅 LICENSE 文件。

参考资料

评论

支持 Markdown

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。