使用说明
NaverMapMcp
使用Naver Map API的模型上下文协议（MCP）服务器。
LLM提供了一个工具（Tool），可以使用“搜索地点”、“坐标转换”和“引导路径”功能。
🚀 主要功能
| Tool | 说明 | API |
|---|---|---|
naver_places |
按地点名称搜索（例如“弘大”、“圣水”） | Naver Developers |
naver_geocode |
地址→坐标转换（x，y）纬度、经度 | Naver Cloud Platform |
naver_directions |
引导两个坐标之间的路径（距离，所需时间） | Naver Cloud Platform |
使用流程示例
"홍대에서 성수까지 얼마나 걸려?"
↓
1. naver_places("홍대") → 주소 획득
2. naver_places("성수") → 주소 획득
↓
3. naver_geocode -> 위도,경도 획득
4. naver_directions(start, goal) → 거리, 소요시간 반환
💡 小贴士：搜索地点名
naver_places只需要使用！
📋 前提条件
1.Naver云平台（地理代码、方向용)
- Naver云平台 订阅
- 控制台→Maps API→应用程序注册
- 地图地理编码, 地图方向5 申请使用API
- 发放Client ID/Client Secret
2.Naver开发者（地点/本地搜索용)
- Naver开发者 订阅
- 注册应用程序
- 搜索>地区 启用API
- 发放Client ID/Client Secret
⚠️ 注意：两个平台的API密钥不同。不要混淆！
安装和运行⚙ENT
1.安装依赖性
uv sync
2.设置环境变量
在项目根目录中 .env 创建文件：
# Naver Cloud Platform (Geocode, Directions)
NAVER_NCP_CLIENT_ID=your_ncp_client_id
NAVER_NCP_CLIENT_SECRET=your_ncp_client_secret
# Naver Developers (Places/Local Search)
NAVER_DEV_CLIENT_ID=your_dev_client_id
NAVER_DEV_CLIENT_SECRET=your_dev_client_secret
3.运行服务器
uv run main.py
服务器 http://0.0.0.0:8002在中运行。
🧪 测试
通过MCP Inspector进行验证
# 다른 터미널에서
npx @modelcontextprotocol/inspector
📁 项目结构
NaverMapMcp/
├── app/
│ ├── services/
│ │ └── naver_map_service.py # Naver API 호출 서비스
│ └── tools/
│ ├── __init__.py
│ ├── directions.py # naver_directions tool
│ ├── geocode.py # naver_geocode tool
│ └── places.py # naver_places tool
├── docs/ # 문서
├── .env # 환경 변수 (git 제외)
├── .gitignore
├── .python-version
├── main.py # MCP 서버 엔트리포인트
├── pyproject.toml
├── uv.lock
└── README.md
🌿 Git分支战略
| 布兰奇 | 说明 |
|---|---|
master |
生产部署分支机构 |
develop |
开发整合分支机构 |
feature/* |
新功能开发分支机构 |
hotfix/* |
错误修复分支 |
分支命名示例
feature/naver-map-directions
feature/geocoding-service
hotfix/cors-middleware-error
hotfix/api-timeout-handling
📝 提交消息规则
Prefix说明示例
|--------|------|------|
| feat |添加新功能| feat: Add Naver Map directions API |
| fix |错误修复| fix: Fix CORS middleware configuration |
| docs |修改文档| docs: Update README with API examples |
| style |代码格式化（功能不变）| style: Format code with Black |
| refactor |代码重构| refactor: Simplify routing service logic |
| test |添加/修改测试代码| test: Add unit tests for geocoding |
| chore |修改构建/配置文件| chore: Update dependencies in pyproject.toml |
