小智AI接高德地图 MCP 教程

小智AI 接高德地图能做什么？

给语音助手接上高德 MCP，等于让它多了一双「会查地图的眼睛」：问天气、查路线、找附近餐厅、发起导航，都能用自然语言完成，不需要你手动开 App。

对小智这类设备（音箱、机器人、桌面助手）尤其实用——它没有触屏，语音 + 地图类工具是天然组合。

小智AI 的 MCP 接入点机制是什么？

根据 xiaozhi-esp32-server 官方文档（docs/mcp-endpoint-enable.md），小智服务端通过配置 mcp_endpoint 参数，连接一个「MCP 接入点服务」。这个接入点由官方项目 mcp-endpoint-server 提供，启动后会输出两个地址：

智控台 MCP 参数配置：http://你的ip:8004/mcp_endpoint/health?key=abc；单模块部署 MCP 接入点：ws://你的ip:8004/mcp_endpoint/mcp/?token=def

小智服务端把 mcp_endpoint 指向这个 ws 地址后，就能发现并调用接入点背后的 MCP 工具。换句话说：接入点是一个「中间层」，小智只连它，工具由它背后挂载。

怎么申请高德开放平台 API Key？

打开高德开放平台（lbs.amap.com），用支付宝/手机号登录，进入「控制台 → 应用管理 → 我的应用」，创建一个「Web 服务」类型应用，即可获得 Key（一串 32 位字符串）。

高德 Web 服务 API 需要实名认证，个人开发者免费额度足够日常使用。把 Key 复制保存好，下一步配置 MCP Server 要用。注意别把 Key 泄露到公开仓库。

高德 MCP Server 有哪些？用哪个？

高德官方与社区都有 MCP Server 实现：sugarforever/amap-mcp-server（GitHub 千星级）是目前最常用的社区实现，支持 stdio、sse 与 streamable-http 三种传输方式，封装了地理编码、路线规划、天气等能力；高德官方也推出了 @amap/amap-maps-mcp-server。

教程以 sugarforever/amap-mcp-server 为例：它需要环境变量 AMAP_KEY 指向你的 Key。接入点（mcp-endpoint-server）以 MCP Client 身份连接它，再把工具聚合给上层的语音助手。

怎么用 Docker 部署 mcp-endpoint-server？

克隆官方项目 xinnan-tech/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",…}} 即成功。

怎么把小智服务端指向接入点？

两种部署方式配置不同。全模块部署（用智控台）：管理员登录后进「参数字典 → 参数管理」，搜索 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 为准）。把高德 MCP Server 的启动方式（如 npx 或 docker 运行 sugarforever/amap-mcp-server，并传入 AMAP_KEY 环境变量）配进去。

重启接入点后，小智服务端就能通过 tools/list 发现高德工具（如地理编码、路线规划、天气查询）。之后对小智说「用高德查一下从北京到上海的路线」即可触发。

接不上 / 不响应怎么办？

① 智控台地址浏览器访问失败：多半是局域网 IP 没替换，或防火墙没放行 8004 端口。② 小智日志显示 mcp 接入点连不上：检查 .config.yaml 里 mcp_endpoint 是否填的 ws 地址而非 http。③ 能连上但语音不触发高德：确认工具已被 tools/list 发现（看接入点日志），并换更明确的指令词，如「导航去北京西站」而不是「去北京」。④ Key 报错：确认高德 Key 是 Web 服务类型且已实名。