amap-location-mcp

一个基于高德开放平台 Web 服务 API 的只读 MCP Server。它的主要用途是让 AstrBot、RikkaHub 等 AI 客户端回答“从这里怎么回家”“从北京南站到故宫怎么走”这类问题：输入起点和终点，自动解析真实高德地点，同时比较步行、驾车和公交，给出距离、预计耗时、关键步骤和推荐交通方式。

它参考了 SHowGS/SillyTavern-RealMap 的“真实地点 + 周边环境 + 路线 + 位置来源”思路，但代码为独立实现，没有复制该项目源码。

优先考虑高德官方 MCP

高德开放平台现已提供官方 MCP Server。对 Cherry Studio、RikkaHub、Cursor、AstrBot 等支持 Streamable HTTP 的客户端，建议优先直连官方服务；官方当前提供 POI 搜索、地理编码、驾车/公交/步行/骑行、距离、天气、导航与打车链接等完整工具：

{
  "mcpServers": {
    "AmapOfficial": {
      "url": "https://mcp.amap.com/mcp?key=你的高德Web服务Key"
    }
  }
}

申请 Key 时仍需在高德开放平台控制台选择“Web 服务”。官方接入说明见快速接入高德地图 MCP Server。Key 位于 URL 查询参数中，请只保存到私有客户端配置，不要提交到 Git。

本仓库继续保留，适合需要以下能力的场景：只向模型暴露一个综合路线工具以减少上下文、在服务端统一 Bearer 鉴权、控制字段裁剪，或自行托管兼容入口。地点容易重名时，无论使用官方还是本项目，都建议给助手加入 navigation-guard-prompt.example.txt 中的约束。

定位边界

• 可以把地址/POI 解析为高德真实 GCJ-02 坐标。

• 可以把调用方主动提供的 WGS84/GPS 坐标转换为 GCJ-02，再查询地址和周边 POI。

• 可以对明确传入的公网 IPv4 做省市级粗定位。

• 不能自行读取电脑、手机或浏览器的 GPS。要获得设备实况位置，需要前端在用户授权后把坐标传给 MCP，并设置 coordinate_source: "device_gps"。

• 不会把 POI 推测、IP 出口或 MCP 服务器位置伪装成用户的设备定位。

每次成功结果都包含：

{
  "source": "amap_reverse_geocode",
  "coordinate_system": "GCJ-02",
  "precision": "point_of_interest",
  "confidence": 0.9,
  "is_device_location": false,
  "observed_at": "...",
  "warnings": []
}

工具

面向 AstrBot/RikkaHub 的导航专用部署建议设置 MCP_TOOL_PROFILE=directions。该模式只向客户端暴露 amap_get_directions，其余能力仍由这个综合工具在服务端内部完成，避免 8 份工具定义长期占用模型上下文。

密钥要求

本项目不会提供或内置高德 Key。使用前必须访问高德地图开放平台，登录后进入控制台创建应用并申请 API Key：

• 服务平台：Web服务

下面两种凭证不能用于本项目：

• Web端（JS API）Key

• securityJsCode / 安全密钥

密钥只从环境变量 AMAP_WEB_SERVICE_KEY 读取，不写入源码或配置模板。JS API 凭证不应放入 .env。

最简单的调用方式

通常只需要让 AI 调用 amap_get_directions：

{
  "origin": "北京南站",
  "destination": "故宫博物院",
  "origin_city": "北京",
  "destination_city": "北京",
  "modes": ["walking", "driving", "transit"]
}

返回内容包括：

• 起点和终点实际匹配到的高德 POI、地址及 GCJ-02 坐标；

• 每种可用交通方式的总距离、预计耗时和关键步骤；

• recommended_mode 与中文推荐理由；

• 某一种路线查询失败时，仍保留其他可用方案。

如果地点重名，传入 origin_city / destination_city 可以减少歧义。modes 可只保留需要比较的方式。

本地安装和 stdio 运行

要求 Node.js 22 或更高版本。

git clone https://github.com/188zjl/amap-location-mcp.git
cd amap-location-mcp
npm install
npm run build
$env:AMAP_WEB_SERVICE_KEY="你的 Web服务 Key"
npm start

本地开发可复制 .env.example 为 .env，再运行 npm run dev。.env 已被 Git 忽略。

服务器 Streamable HTTP 模式

AstrBot 和 RikkaHub 可以共用部署在服务器上的兼容入口。服务本身默认只监听 127.0.0.1:3000，应由 Nginx、Nginx Proxy Manager 或 Caddy 提供 HTTPS：

export AMAP_WEB_SERVICE_KEY="你的 Web服务 Key"
export MCP_TRANSPORT="http"
export MCP_AUTH_TOKEN="至少16位的随机访问令牌"
export MCP_TOOL_PROFILE="directions"
export MCP_ALLOWED_HOSTS="map-mcp.example.com"
npm start

MCP 地址为 http://127.0.0.1:3000/mcp，健康检查为 http://127.0.0.1:3000/health。反向代理时需要：

• 将公网 https://map-mcp.example.com/mcp 转发到 http://127.0.0.1:3000/mcp；

• 保留 Authorization 请求头；

• 将真实公网域名写入 MCP_ALLOWED_HOSTS；

• 不要直接把 Node 端口暴露到公网；

• /health 只说明 HTTP 服务存活，最终应以真实 tools/list 和 amap_get_directions 调用为准。

可选变量见 .env.example。HTTP 模式强制 Bearer Token，且令牌至少 16 个字符。

AstrBot 配置

在 AstrBot 面板的“扩展/工具 → MCP Servers → 添加服务器”中使用 Streamable HTTP，并填入：

{
  "transport": "streamable_http",
  "url": "https://map-mcp.example.com/mcp",
  "headers": {
    "Authorization": "Bearer 你的访问令牌"
  },
  "timeout": 10,
  "sse_read_timeout": 300
}

RikkaHub 配置

复制仓库中的 rikkahub-amap-directions.example.json，替换域名和访问令牌后即可导入 RikkaHub：

{
  "mcpServers": {
    "AmapDirections": {
      "type": "streamable_http",
      "url": "https://map-mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer 你的访问令牌"
      }
    }
  }
}

注意：AstrBot 使用字段 transport，RikkaHub 使用字段 type。

其他本地 MCP 客户端配置

Codex 的 config.toml 示例：

[mcp_servers.amap-location]
command = "node"
args = ["C:\\path\\to\\amap-location-mcp\\dist\\index.js"]
env = { AMAP_WEB_SERVICE_KEY = "你的 Web服务 Key" }

使用 JSON 配置的 MCP 客户端可写成：

{
  "mcpServers": {
    "amap-location": {
      "command": "node",
      "args": ["C:\\path\\to\\amap-location-mcp\\dist\\index.js"],
      "env": {
        "AMAP_WEB_SERVICE_KEY": "你的 Web服务 Key"
      }
    }
  }
}

其他调用示例

解析地点：

{
  "query": "北京大学",
  "city": "北京",
  "current_location": {
    "longitude": 116.31,
    "latitude": 39.99
  }
}

设备授权后传入 WGS84 GPS 坐标：

{
  "location": {
    "longitude": 116.397,
    "latitude": 39.908
  },
  "coordinate_system": "WGS84",
  "coordinate_source": "device_gps",
  "include_nearby_pois": true
}

构建 AI 位置上下文：

{
  "query": "北京大学",
  "city": "北京",
  "nearby_keywords": "咖啡",
  "radius": 800,
  "nearby_limit": 8
}

验证

npm run check

验证内容包括 TypeScript 构建、mock 高德响应、候选排序、WGS84 转换、逆地理编码、组合上下文、路线归一化，以及 MCP stdio 的旧版与 2026-07-28 协议握手、tools/list 和 tools/call。

高德官方文档

• 高德地图 MCP Server 快速接入

• 地理/逆地理编码

• POI 搜索

• IP 定位

• 坐标转换

• 路径规划

开源许可

本项目使用 MIT License 开源。