小智AI接高德地图 MCP 教程:mcp-endpoint-server 部署到导航生效
小智AI 接高德 MCP 的核心是给服务端配一个「MCP 接入点」:① 用 Docker 部署官方 mcp-endpoint-server,得到 ws://你的ip:8004/mcp_endpoint/mcp/?token=xxx 形式的接入点;② 申请高德开放平台 Web 服务 API Key;③ 在接入点里配置高德 MCP Server;④ 把小智服务端 mcp_endpoint 参数指向该接入点。配好后对小智说「导航去机场」即可触发高德工具。
想让小智AI 语音助手直接问你「附近哪里有好吃的」「导航去机场」,需要给它接上高德地图 MCP。本教程按 xiaozhi-esp32-server 官方架构,从部署接入点到配置高德 MCP 一步步来,约 10 分钟完成。
小智AI 接高德地图能做什么?
接上高德 MCP,等于给语音助手加了一双「会查地图的眼睛」:
- 查天气:问「北京今天多少度」,助手调工具拿到实时天气念给你听
- 查路线:「从上海虹桥到浦东机场怎么走」,返回驾车/公交方案
- 找附近:「附近有什么川菜馆」,按位置推荐并给地址
- 发起导航:「导航去北京西站」,直接下发导航指令
小智这类设备(音箱、机器人、桌面助手)没有触屏,语音 + 地图是天然组合。
小智AI 的 MCP 接入点机制是什么?
根据 xiaozhi-esp32-server 官方文档(docs/mcp-endpoint-enable.md),小智服务端通过配置 mcp_endpoint 参数,连接一个「MCP 接入点服务」。
接入点由官方项目 mcp-endpoint-server 提供,启动后输出两个地址:
- 智控台配置地址:
http://你的ip:8004/mcp_endpoint/health?key=abc - 单模块接入地址:
ws://你的ip:8004/mcp_endpoint/mcp/?token=def
小智服务端把 mcp_endpoint 指向这个 ws 地址后,就能发现并调用接入点背后的工具。接入点 = 中间层:小智只连它,工具由它背后挂载。
本教程的「接入点」概念,与小智MCP 提供的托管接入点一致;区别只是自部署 vs 免运维。
怎么申请高德开放平台 API Key?
- 打开高德开放平台(lbs.amap.com),用支付宝或手机号登录
- 进入「控制台 → 应用管理 → 我的应用」
- 创建一个 Web 服务 类型应用
- 获得 Key(一串 32 位字符串),复制保存
高德 Web 服务 API 需实名认证;Key 千万别提交到公开 GitHub 仓库。
个人开发者免费额度足够日常使用。
高德 MCP Server 有哪些?用哪个?
高德官方与社区都有 MCP Server 实现,最常用的是社区版:
- sugarforever/amap-mcp-server(GitHub 千星级):支持 stdio、sse、streamable-http 三种传输,封装地理编码、路线规划、天气、POI 搜索等能力
- @amap/amap-maps-mcp-server:高德官方推出
本教程用 sugarforever/amap-mcp-server 举例。它读取环境变量 AMAP_KEY 作为你的 Key。
怎么用 Docker 部署 mcp-endpoint-server?
克隆官方项目后,在根目录启动:
git clone https://github.com/xinnan-tech/mcp-endpoint-server
cd mcp-endpoint-server
docker compose -f docker-compose.yml up -d
docker logs -f mcp-endpoint-server
日志里会出现两个地址(见上文架构节)。关键一步:Docker 部署时打印的是容器内网 IP(如 172.x.x.x),要换成你电脑的局域网 IP(如 192.168.1.25)。
用浏览器访问智控台地址,看到下面返回即成功:
{"result":{"status":"success","connections":{"tool_connections":0}},"error":null,"id":null,"jsonrpc":"2.0"}
怎么把小智服务端指向接入点?
分两种部署方式:
全模块部署(用智控台)
管理员登录 → 「参数字典 → 参数管理」→ 搜索 server.mcp_endpoint → 把「智控台 MCP 参数配置」地址粘贴进去保存。
单模块部署(改配置文件)
编辑 data/.config.yaml,在 server 节下加一行:
mcp_endpoint: ws://你的ip:8004/mcp_endpoint/mcp/?token=def
保存重启后,日志出现「mcp接入点是 ws://…」即配置成功。
接入点怎么连上高德 MCP Server?
在 mcp-endpoint-server 的配置里声明要挂载的 MCP Server(不同版本配置方式略有差异,以项目 README 为准):
# 用 docker 运行高德 MCP server,并传入你的 Key
docker run -e AMAP_KEY=你的Key sugarforever/amap-mcp-server
重启接入点后,小智服务端就能通过 tools/list 发现高德工具。对小智说「用高德查一下从北京到上海的路线」即可触发。
触发词尽量带「高德」+ 明确地点,如「导航去北京西站」比「去北京」成功率高得多。
接不上 / 不响应怎么办?
按现象对号入座:
- 智控台地址浏览器访问失败:局域网 IP 没替换,或防火墙没放行 8004 端口
- 小智日志显示接入点连不上:检查 mcp_endpoint 填的是 ws 地址而不是 http
- 能连上但语音不触发:看接入点日志确认 tools/list 里有没有高德工具;换更明确的指令词
- 报 Key 错误:确认高德 Key 是 Web 服务类型且已完成实名