使用说明
导航地图MCP服务器
NAVER地图API 模型上下文协议（MCP） 工具提供的服务器。Claude Desktop、Claude Code、VS Code等MCP客户端可以使用NAVER地图功能。
主要功能
- 地址→坐标转换 （Geocoding）：将道路名/编号地址转换为经度、纬度坐标
- 坐标→地址转换 （Reverse Geocoding）：将坐标转换为法庭洞、行政洞、道路名和编号地址
- 浏览路径 （Directions）：出发地-计算目的地之间的距离、所需时间、通行费、出租车费、燃油费
- 创建静态地图图像 （Static Map）：创建包含标记、路径的地图图像
- 查看API使用情况 （Usage）：查看每月使用情况、成本和免费限额使用率
安全注意事项
注意： 该服务器访问NAVER Cloud API，如果超过免费限额，可能会收取费用。
- 不要将API密钥暴露在代码或公共存储库中
- 通过环境变量或配置文件进行安全管理
- 超过免费限额将根据使用情况收费
navermap_get_usage请使用工具定期检查使用情况
安装
npm install -g @flor3z-github/navermap-mcp-server
或者直接运行npx：
npx -y @flor3z-github/navermap-mcp-server
设置环境变量
必需（Maps API）
Naver云平台在中创建应用程序并获得API密钥。
NAVER_CLIENT_ID=your_client_id
NAVER_CLIENT_SECRET=your_client_secret
选择（Billing API-查看使用情况）
使用查询功能需要额外的密钥：
NCLOUD_ACCESS_KEY=your_access_key
NCLOUD_SECRET_KEY=your_secret_key
即使没有Billing API密钥，其余4个工具也能正常工作。
客户端设置
克劳德桌面版
claude_desktop_config.json 在文件中添加以下内容：
使用全部功能：
{
"mcpServers": {
"navermap": {
"command": "npx",
"args": ["-y", "@flor3z-github/navermap-mcp-server"],
"env": {
"NAVER_CLIENT_ID": "your_client_id",
"NAVER_CLIENT_SECRET": "your_client_secret",
"NCLOUD_ACCESS_KEY": "your_access_key",
"NCLOUD_SECRET_KEY": "your_secret_key"
}
}
}
}
仅使用Maps API：
{
"mcpServers": {
"navermap": {
"command": "npx",
"args": ["-y", "@flor3z-github/navermap-mcp-server"],
"env": {
"NAVER_CLIENT_ID": "your_client_id",
"NAVER_CLIENT_SECRET": "your_client_secret"
}
}
}
}
VS Code
.vscode/mcp.json 或自定义的 mcp.json添加到：
{
"servers": {
"navermap": {
"command": "npx",
"args": ["-y", "@flor3z-github/navermap-mcp-server"],
"env": {
"NAVER_CLIENT_ID": "your_client_id",
"NAVER_CLIENT_SECRET": "your_client_secret"
}
}
}
}
克劳德代码
claude mcp add navermap \
--env NAVER_CLIENT_ID=your_client_id \
--env NAVER_CLIENT_SECRET=your_client_secret \
--env NCLOUD_ACCESS_KEY=your_access_key \
--env NCLOUD_SECRET_KEY=your_secret_key \
-- npx -y @flor3z-github/navermap-mcp-server
仅使用Maps API：
claude mcp add navermap \
--env NAVER_CLIENT_ID=your_client_id \
--env NAVER_CLIENT_SECRET=your_client_secret \
-- npx -y @flor3z-github/navermap-mcp-server
交付工具
所有工具均为只读（readOnlyHint: true），不更改数据。
1.navermap_geocode
将地址转换为坐标。
参数：
| 名称 | 必需 | 说明 |
|---|---|---|
| 查询O要搜索的地址 | ||
| coordinableX | 搜索中心坐标（经度、纬度） | |
| filter | X | 结果过滤器（例如HCODE:168000000） |
| language | X | 响应语言（ko，en，ja，zh） |
| page | X | 页码 |
| 计数X结果数（最多100） |
使用示例：
"서울특별시 강남구 테헤란로 152" 주소의 좌표를 알려줘
2.navermap_reverse_geocode
将坐标转换为地址。
参数：
| 名称 | 必需 | 说明 |
|---|---|---|
| 坐标（经度、纬度格式） | ||
| sourcecrs X输入坐标系 | ||
| targetcrs | X | 输出坐标系 |
| 订单 | X | 응답 순서 （法律代码、行政代码、地址、道路地址） |
| 输出X响应格式（json，xml） |
使用示例：
127.0368,37.5085 좌표의 주소를 알려줘
3.navermap_get_directions
导航路径并提供距离、所需时间和成本信息。
参数：
| 名称 | 必需 | 说明 |
|---|---|---|
| 开始O出发地坐标（经度、纬度） | ||
| goal | O | 目的地坐标（经度、纬度） |
| waypoints | X | 经由地（最多5个，以 |
| 选项 | X | 경로 옵션 （trafast、tracomfort、traoptimal、traavoidtoll、traavoid caronly） |
| cartype | X | 车辆类型（1-6） |
| fueltype X燃料种类 | ||
| mileage | X | 燃油效率（km/L） |
路径选项：
trafast：实时快速通道tracomfort：舒服的路traoptimal：最佳（默认）traavoidtoll：免费优先traavoidcaronly：避开汽车专用道
使用示例：
강남역에서 여의도까지 경로 알려줘
4.navermap_get_static_map
创建静态地图图像。
参数：
| 名称 | 必需 | 说明 |
|---|---|---|
| 中心坐标（经度、纬度） | ||
| level | X | 缩放级别（1-20，默认值：16） |
| 图像宽度（最大1024） | ||
| 图像高度（最高1024） | ||
| 地图类型（basic，traffic，satellite，satellite_base，terrain） | ||
| markers | X | 标记设置 |
| 路径X设置路径 | ||
| 图像缩放（1或2） |
使用示例：
서울역 주변 지도를 보여줘
5.navermap_get_usage
查看API使用情况和成本。（需要NCLOUD_ACCESS_KEY、NCLOUD_SECRET_KEY）
参数：
| 名称 | 必需 | 说明 |
|---|---|---|
| month | X | 要查询的月份（YYYY-MM，默认值：当月） |
使用示例：
이번 달 네이버 지도 API 사용량 알려줘
示例响应：
## 2024-12 Naver Maps API 사용량 현황
### 경고
- Directions 5 사용률이 75.0%입니다. 한도에 주의하세요.
### 서비스별 사용량
| 서비스 | 사용량 | 무료한도 | 사용률 | 비용 |
|--------|--------|----------|--------|------|
| Directions 5 | 45,000 | 60,000 | 75.0% | 0원 |
| Geocoding | 1,500,000 | 3,000,000 | 50.0% | 0원 |
| ... | ... | ... | ... | ... |
### 총 비용: 0원
免费使用量指南
Naver Maps API每月提供免费使用：
| 服务 | 免费限额（周一） |
|---|---|
| 动态地图 | 6000000건 |
| 静态地图 | 3000000건 |
| Geocoding 3000000件 | |
| 反向地理编码 | 3000000건 |
| Directions 5（5个经由地） | 60000件 |
| Directions 15（15个经由地） | 3000个 |
超过免费限额时，根据使用量收费。有关详细信息，请访问 Naver Cloud Platform费用指南请参阅。
开发
安装和构建
# 의존성 설치
npm install
# 빌드
npm run build
# 개발 모드 (tsx로 직접 실행)
npm run dev
测试
# 테스트 실행
npm test
# 커버리지 포함 테스트
npm run test:coverage
代码质量
# 린트 검사
npm run lint
# 코드 포맷팅
npm run format
调试
MCP检查员可以使用调试服务器：
npm run inspector
# 또는
npx @modelcontextprotocol/inspector npx -y @flor3z-github/navermap-mcp-server
环境变量
可以将行为调整为其他环境变量：
| 变量 | 默认值 | 说明 |
|---|---|---|
| LOG_LEVEL | info | 日志级别（debug、info、warn、error） |
| REQUEST_TIMEOUT | 30000 | API请求超时（ms） |
| MAX_RETRIES | 3 | 失败时重试次数 |
贡献
欢迎您的贡献！请发送Pull Request。
许可证
阿帕奇-2.0
