amap-location-mcp

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

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

定位边界

• 可以把地址/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": []
}

工具

工具	用途
amap_get_directions	主要入口：输入起点、终点地址或地点，同时查询步行、驾车、公交并推荐交通方式
amap_resolve_location	地点/地址解析、候选排序和城市消歧
amap_reverse_geocode	GCJ-02/WGS84 坐标转结构化地址和附近 POI
amap_search_nearby	按半径、关键词或 POI 类型搜索周边
amap_convert_coordinates	WGS84、百度、Mapbar 坐标转高德 GCJ-02
amap_locate_ip	定位明确传入的 IPv4，结果仅为省市级粗定位
amap_plan_route	步行、驾车、公交路线规划
amap_build_location_context	一次组合地点解析、地址和周边证据，供 AI 直接使用

面向 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。

高德官方文档

• 地理/逆地理编码
• POI 搜索
• IP 定位
• 坐标转换
• 路径规划

开源许可

本项目使用 MIT License 开源。