Serves as the framework for the MCP server, handling WebSocket connections and providing endpoints for the navigation service.
Powers the client-side functionality of the interactive map interface that displays navigation routes in real-time.
高德地图导航 MCP Tool
这是一个基于 FastAPI 和 fastmcp 的高德地图导航 MCP (Model Context Protocol) 工具。该工具提供了一个交互式的地图页面,支持驾车、骑行、步行三种导航类型,可以通过 MCP 接口发送导航命令进行实时路线规划。系统采用 WebSocket 实时通信和基于 sessionid 的会话管理,确保多用户使用的安全性和独立性。
⚠️ 重要安全声明
本服务仅用于学习和开发测试目的,严禁在生产环境中使用!
- 🔒 API 密钥暴露风险:高德地图 API 密钥通过 URL 参数传递,存在暴露风险
- 🌐 公网访问危险:未实施密钥加密和访问控制,不得部署到公网
- 📊 日志泄露风险:密钥可能被记录在服务器访问日志中
- 🔐 无安全防护:缺乏 HTTPS、密钥加密、访问限制等安全措施
使用建议:
- ✅ 仅在本地开发环境使用
- ✅ 使用测试用的 API 密钥
- ✅ 确保防火墙阻止外部访问
- ❌ 禁止使用生产环境密钥
- ❌ 禁止部署到公网服务器
🏗️ 架构设计
- 会话管理:基于 sessionid 的多用户会话隔离系统
- 地图页面:FastAPI 提供的交互式 HTML 页面,需要有效的 sessionid 才能访问
- WebSocket 通信:实时双向通信,支持导航命令的即时推送
- MCP Tools:
create_session
创建会话,send_navigation_to_map
发送导航命令 - 多种导航类型:支持驾车、骑行、步行三种导航模式
- 混合输入:支持经纬度坐标和关键字地点混合使用
🚀 快速开始
1. 环境设置
我们使用 uv
进行 Python 环境管理。首先确保已安装 uv
:
2. 安装依赖
3. 设置环境变量(可选)
如果你有自己的高德地图 API 密钥,可以设置环境变量:
4. 启动服务器
服务器启动后,你会看到以下信息:
🔌 API 接口
主要端点
端点 | 方法 | 说明 |
---|---|---|
/ | GET | 获取地图页面(���要 sessionid 参数) |
/ws/{session_id} | WebSocket | WebSocket 连接端点 |
/sessions | GET | 查看所有活跃会话 |
/queue-status | GET | 查看命令队列状态 |
/health | GET | 健康检查 |
/mcp | - | MCP 协议端点 |
/static | GET | 静态文件服务 |
查看系统状态
🗝️ 获取高德地图 API Key
- 访问 高德开放平台
- 注册账号并登录
- 创建应用并获取 API Key
- 在 Web 服务中启用 JavaScript API
🎬 使用流程
- 设置环境变量 → (可选)设置
AMAP_API_KEY
和AMAP_SECURITY_CODE
- 启动服务 → 运行
python main.py
- 创建会话 → 使用 MCP tool
create_session
- 访问地图 → 使用返回的完整链接访问地图页面(包含密钥参数)
- 发送导航命令 → 使用 MCP tool
send_navigation_to_map
- 查看结果 → 地图通过 WebSocket 实时显示导航路线
🌟 特色功能
- WebSocket 实时通信:地图页面通过 WebSocket 实时接收导航命令
- 会话隔离:每个用户有独立的地图会话和连接
- 多种导航类型:支持驾车、骑行、步行导航
- 混合输入:支持经纬度坐标和关键字混合使用
- 自动重连:WebSocket 连接断开时自动重连
- 安全访问:基于 sessionid 的访问控制
- 环境变量支持:支持通过环境变量设置自定义 API 密钥
- URL 参数传递:密钥通过 URL 参数动态传递,灵活安全
- 响应式设计:适配各种屏幕尺寸
📂 项目结构
🛠️ 技术栈
- FastAPI: 现代、快速的 Web 框架,支持 WebSocket
- fastmcp: MCP (Model Context Protocol) 实现
- uvicorn: ASGI 服务器
- WebSocket: 实时双向通信协议
- 高德地图 JavaScript API: 地图、驾车、骑行、步行导航服务
⚠️ 注意事项
- 🔐 安全第一:本服务仅用于学习测试,严禁生产环境使用!
- 🔑 密钥安全:API 密钥通过 URL 参数传递,存在泄露风险,仅限本地使用
- 🌐 网络要求:需要网络连接加载地图资源
- 🔒 会话管理:必须先创建会话才能访问地图页面
- 💻 浏览器兼容:建议在现代浏览器中使用(支持 WebSocket)
- 📍 坐标系统:坐标使用 WGS84 坐标系统
- 🚲 导航限制:骑行和步行导航不支持 policy 参数
- 🔍 搜索要求:关键字搜索时必须提供城市信息
- 📝 日志风险:密钥可能被记录在各级日志中,注意清理
- 🔒 访问控制:确保服务只在可信网络中运行
🤝 贡献
欢迎提交 Issues 和 Pull Requests!
📄 许可证
MIT License
免责声明: 本项目仅用于学习和技术研究目的。使用者应当:
- 遵守高德地图API使用条款
- 不得将本项目用于商业生产环境
- 自行承担API密钥泄露等安全风险
- 确保符合当地法律法规要求
作者不承担因使用本项目而产生的任何直接或间接损失。
This server cannot be installed
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
A FastAPI and fastmcp based Amap Navigation MCP tool that provides interactive map navigation with real-time route planning and WebSocket communication.
Related MCP Servers
- -securityAlicense-qualityFastMCP is a comprehensive MCP server allowing secure and standardized data and functionality exposure to LLM applications, offering resources, tools, and prompt management for efficient LLM interactions.Last updated -3PythonMIT License
- AsecurityAlicenseAqualityAn MCP server that creates a virtual traveling environment on Google Maps, allowing users to guide an avatar on journeys with photo reports and SNS integration.Last updated -22012TypeScriptMIT License
- -securityFlicense-qualitykakao navigation mcp server using kakao mobility & kakao map apiLast updated -1TypeScriptMIT License
- -security-license-qualityProvides access to Google Maps API functionality including geocoding, place search, direction routing, and distance calculations through a structured MCP interface.Last updated -JavaScriptMIT License