Skip to main content
Glama

AMapMCP

by Zhangtiande

高德地图导航 MCP Tool

简体中文 | 日本語 | English

这是一个基于 FastAPI 和 fastmcp 的高德地图导航 MCP (Model Context Protocol) 工具。该工具提供了一个交互式的地图页面,支持驾车、骑行、步行三种导航类型,可以通过 MCP 接口发送导航命令进行实时路线规划。系统采用 WebSocket 实时通信和基于 sessionid 的会话管理,确保多用户使用的安全性和独立性。

⚠️ 重要安全声明

本服务仅用于学习和开发测试目的,严禁在生产环境中使用!

  • 🔒 API 密钥暴露风险:高德地图 API 密钥通过 URL 参数传递,存在暴露风险
  • 🌐 公网访问危险:未实施密钥加密和访问控制,不得部署到公网
  • 📊 日志泄露风险:密钥可能被记录在服务器访问日志中
  • 🔐 无安全防护:缺乏 HTTPS、密钥加密、访问限制等安全措施

使用建议:

  • ✅ 仅在本地开发环境使用
  • ✅ 使用测试用的 API 密钥
  • ✅ 确保防火墙阻止外部访问
  • ❌ 禁止使用生产环境密钥
  • ❌ 禁止部署到公网服务器

🏗️ 架构设计

  • 会话管理:基于 sessionid 的多用户会话隔离系统
  • 地图页面:FastAPI 提供的交互式 HTML 页面,需要有效的 sessionid 才能访问
  • WebSocket 通信:实时双向通信,支持导航命令的即时推送
  • MCP Toolscreate_session 创建会话,send_navigation_to_map 发送导航命令
  • 多种导航类型:支持驾车、骑行、步行三种导航模式
  • 混合输入:支持经纬度坐标和关键字地点混合使用

🚀 快速开始

1. 环境设置

我们使用 uv 进行 Python 环境管理。首先确保已安装 uv

# 安装 uv(如果尚未安装) curl -LsSf https://astral.sh/uv/install.sh | sh # 创建新的虚拟环境 uv venv # 激活虚拟环境 source .venv/bin/activate # Linux/macOS .venv\Scripts\activate # Windows

2. 安装依赖

# 使用 uv 安装依赖 uv pip install -r requirements.txt # 同步依赖(推荐) uv sync

3. 设置环境变量(可选)

如果你有自己的高德地图 API 密钥,可以设置环境变量:

# 设置环境变量 export AMAP_API_KEY="你的高德地图API密钥" export AMAP_SECURITY_CODE="你的高德地图安全密钥"

4. 启动服务器

# 直接运行 python main.py # 或者使用 uvicorn uvicorn main:app --host 0.0.0.0 --port 8000

服务器启动后,你会看到以下信息:

🚀 启动高德地图导航 MCP 服务器... 🔧 MCP 端点: http://localhost:8000/mcp 📚 API 文档: http://localhost:8000/docs 使用说明: 1. 使用 MCP tool 'create_session' 创建会话 2. 使用返回的 sessionid 访问地图页面 3. 使用 MCP tool 'send_navigation_to_map' 发送导航命令

🔌 API 接口

主要端点

端点方法说明
/GET获取地图页面(���要 sessionid 参数)
/ws/{session_id}WebSocketWebSocket 连接端点
/sessionsGET查看所有活跃会话
/queue-statusGET查看命令队列状态
/healthGET健康检查
/mcp-MCP 协议端点
/staticGET静态文件服务

查看系统状态

# 查看所有会话 curl "http://localhost:8000/sessions" # 查看命令队列状态 curl "http://localhost:8000/queue-status" # 健康检查 curl "http://localhost:8000/health"

🗝️ 获取高德地图 API Key

  1. 访问 高德开放平台
  2. 注册账号并登录
  3. 创建应用并获取 API Key
  4. 在 Web 服务中启用 JavaScript API

🎬 使用流程

  1. 设置环境变量 → (可选)设置 AMAP_API_KEYAMAP_SECURITY_CODE
  2. 启动服务 → 运行 python main.py
  3. 创建会话 → 使用 MCP tool create_session
  4. 访问地图 → 使用返回的完整链接访问地图页面(包含密钥参数)
  5. 发送导航命令 → 使用 MCP tool send_navigation_to_map
  6. 查看结果 → 地图通过 WebSocket 实时显示导航路线

🌟 特色功能

  • WebSocket 实时通信:地图页面通过 WebSocket 实时接收导航命令
  • 会话隔离:每个用户有独立的地图会话和连接
  • 多种导航类型:支持驾车、骑行、步行导航
  • 混合输入:支持经纬度坐标和关键字混合使用
  • 自动重连:WebSocket 连接断开时自动重连
  • 安全访问:基于 sessionid 的访问控制
  • 环境变量支持:支持通过环境变量设置自定义 API 密钥
  • URL 参数传递:密钥通过 URL 参数动态传递,灵活安全
  • 响应式设计:适配各种屏幕尺寸

📂 项目结构

08.amap/ ├── main.py # 主程序文件 ├── main.js # 客户端JavaScript文件 ├── main.html # 地图页面HTML文件 ├── pyproject.toml # 项目配置文件 ├── README.md # 项目说明文档(中文) ├── README_EN.md # Project documentation (English) ├── README_JA.md # プロジェクトドキュメント(日本語) └── uv.lock # 依赖锁定文件

🛠️ 技术栈

  • FastAPI: 现代、快速的 Web 框架,支持 WebSocket
  • fastmcp: MCP (Model Context Protocol) 实现
  • uvicorn: ASGI 服务器
  • WebSocket: 实时双向通信协议
  • 高德地图 JavaScript API: 地图、驾车、骑行、步行导航服务

⚠️ 注意事项

  1. 🔐 安全第一:本服务仅用于学习测试,严禁生产环境使用!
  2. 🔑 密钥安全:API 密钥通过 URL 参数传递,存在泄露风险,仅限本地使用
  3. 🌐 网络要求:需要网络连接加载地图资源
  4. 🔒 会话管理:必须先创建会话才能访问地图页面
  5. 💻 浏览器兼容:建议在现代浏览器中使用(支持 WebSocket)
  6. 📍 坐标系统:坐标使用 WGS84 坐标系统
  7. 🚲 导航限制:骑行和步行导航不支持 policy 参数
  8. 🔍 搜索要求:关键字搜索时必须提供城市信息
  9. 📝 日志风险:密钥可能被记录在各级日志中,注意清理
  10. 🔒 访问控制:确保服务只在可信网络中运行

🤝 贡献

欢迎提交 Issues 和 Pull Requests!

📄 许可证

MIT License

免责声明: 本项目仅用于学习和技术研究目的。使用者应当:

  • 遵守高德地图API使用条款
  • 不得将本项目用于商业生产环境
  • 自行承担API密钥泄露等安全风险
  • 确保符合当地法律法规要求

作者不承担因使用本项目而产生的任何直接或间接损失。

-
security - not tested
A
license - permissive license
-
quality - not tested

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.

  1. ⚠️ 重要安全声明
    1. 🏗️ 架构设计
      1. 🚀 快速开始
        1. 环境设置
        2. 安装依赖
        3. 设置环境变量(可选)
        4. 启动服务器
      2. 🔌 API 接口
        1. 主要端点
        2. 查看系统状态
      3. 🗝️ 获取高德地图 API Key
        1. 🎬 使用流程
          1. 🌟 特色功能
            1. 📂 项目结构
              1. 🛠️ 技术栈
                1. ⚠️ 注意事项
                  1. 🤝 贡献
                    1. 📄 许可证

                      Related MCP Servers

                      • -
                        security
                        A
                        license
                        -
                        quality
                        FastMCP 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 -
                        3
                        Python
                        MIT License
                      • A
                        security
                        A
                        license
                        A
                        quality
                        An 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 -
                        2
                        20
                        12
                        TypeScript
                        MIT License
                        • Linux
                        • Apple
                      • -
                        security
                        F
                        license
                        -
                        quality
                        kakao navigation mcp server using kakao mobility & kakao map api
                        Last updated -
                        1
                        TypeScript
                        MIT License
                      • -
                        security
                        -
                        license
                        -
                        quality
                        Provides access to Google Maps API functionality including geocoding, place search, direction routing, and distance calculations through a structured MCP interface.
                        Last updated -
                        JavaScript
                        MIT License

                      View all related MCP servers

                      MCP directory API

                      We provide all the information about MCP servers via our MCP API.

                      curl -X GET 'https://glama.ai/api/mcp/v1/servers/Zhangtiande/AMapMCP'

                      If you have feedback or need assistance with the MCP directory API, please join our Discord server