Navermap MCP Server

导航地图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）

参数：

使用示例：

이번 달 네이버 지도 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每月提供免费使用：

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

环境变量

可以将行为调整为其他环境变量：

贡献

欢迎您的贡献！请发送Pull Request。

许可证

阿帕奇-2.0