MCP Map Server

为 LLM 大模型提供地图能力的 MCP (Model Context Protocol) Server。支持高德地图与百度地图的 Web 服务 API，涵盖地理编码、逆地理编码、POI 搜索、周边搜索、路径规划、距离测量、天气查询和 IP 定位。部署后可直接被支持 MCP 的大模型客户端（Claude、Cherry Studio、Cline 等）调用。

功能

• 地理编码 / 逆地理编码（地址 ⇄ 坐标）
• 关键字 POI 搜索与周边搜索
• 路径规划：驾车 / 步行 / 公交 / 骑行
• 距离与耗时测量
• 天气查询（实时 + 未来预报）
• IP 定位
• 双平台支持：高德（amap）、百度（baidu），可按工具调用动态切换
• 两种传输模式：stdio（本地）和 sse（远程 HTTP）
• 统一坐标格式 经度,纬度，屏蔽两家 API 的坐标顺序差异

快速开始

1. 申请 API Key

平台	申请地址	环境变量
高德地图	https://console.amap.com/dev/key/app （创建「Web 服务」类型 Key）	MCP_AMAP_KEY
百度地图	https://lbsyun.baidu.com/apiconsole/key （创建「服务端」应用，得到 AK）	MCP_BAIDU_KEY

两个平台至少配置一个即可。未配置的平台会自动标记为不可用。

⚠️ 高德 Key 的服务平台必须选「Web服务」，用 Web端(JS)/Android/iOS 类型的 Key 调用 Web 服务 API 会报 USERKEY_PLAT_NOMATCH。若该 Key 开启了「数字签名」，还需把私钥填入 MCP_AMAP_SECRET。

2. 克隆仓库

git clone https://github.com/ganyu123456/mcp-map-server.git
cd mcp-map-server

3. 本地开发运行

# 安装依赖
pip install -e ".[sse]"

# 配置环境变量
cp .env.example .env
vim .env   # 填入 MCP_AMAP_KEY / MCP_BAIDU_KEY

# stdio 模式（本地 MCP 客户端）
MCP_TRANSPORT=stdio python -m mcp_map_server.server

# SSE 模式（远程 MCP 客户端）
MCP_TRANSPORT=sse python -m mcp_map_server.server

部署

Docker Compose

cp .env.example .env
# 编辑 .env：填入 API Key，并设置 MCP_IMAGE 指向你的镜像
docker compose up -d

CI/CD 自动构建发布

在仓库 Settings → Secrets and variables → Actions 中添加以下 Secrets（用于推送镜像到 Harbor）：

Secret	示例值	说明
HARBOR_USERNAME	admin	Harbor 用户名
HARBOR_PASSWORD	your-password-or-token	Harbor 密码或访问令牌

镜像仓库地址已固定为 harbor.zkjgy.online/library（写死在 workflow 中），无需再配置 HARBOR_REGISTRY / HARBOR_PROJECT。

打 tag 触发构建：

git tag v1.0.0
git push origin v1.0.0

GitHub Actions 将自动构建 linux/amd64 与 linux/arm64 多架构镜像、推送到 Harbor，并创建带离线镜像的 GitHub Release。

MCP 客户端配置

SSE（远程）

{
  "mcpServers": {
    "map": {
      "url": "http://<your-server-ip>:8091/sse"
    }
  }
}

stdio（本地）

{
  "mcpServers": {
    "map": {
      "command": "python",
      "args": ["-m", "mcp_map_server.server"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "MCP_AMAP_KEY": "your_amap_key",
        "MCP_BAIDU_KEY": "your_baidu_ak"
      }
    }
  }
}

环境变量

变量	默认值	说明
MCP_IMAGE	harbor.zkjgy.online/library/mcp-map-server:latest	Docker 镜像地址
MCP_TRANSPORT	sse	传输模式：stdio 或 sse
MCP_HOST	0.0.0.0	SSE 模式监听地址
MCP_PORT	8091	SSE 模式监听端口
MCP_ENABLED_PLATFORMS	amap,baidu	启用的地图平台
MCP_DEFAULT_PLATFORM	amap	工具调用未指定平台时的默认平台
MCP_AMAP_KEY	(空)	高德地图 Web 服务 Key（服务平台须为「Web服务」）
MCP_AMAP_SECRET	(空)	高德数字签名私钥（仅当 Key 开启「数字签名」时填写）
MCP_BAIDU_KEY	(空)	百度地图 Web 服务 AK
MCP_VERSION	latest	版本标签

MCP 工具列表

工具	说明
map_geocode	地理编码：地址 → 坐标（含 adcode，可用于天气）
map_reverse_geocode	逆地理编码：坐标 → 地址
map_search_poi	关键字 POI 搜索
map_search_around	周边搜索（指定中心 + 半径）
map_direction	路径规划（驾车/步行/公交/骑行）
map_distance	距离与耗时测量
map_weather	天气查询（adcode）
map_ip_location	IP 定位
map_get_platform_status	查询平台可用状态

每个工具（除状态查询外）都支持 platform 参数（amap 或 baidu），省略时使用 MCP_DEFAULT_PLATFORM。

坐标说明

• 所有工具的坐标统一使用 经度,纬度 格式，如 116.481,39.990。
• 坐标与平台绑定：高德返回 GCJ-02，百度返回 BD-09，两者不可跨平台混用。请使用哪个平台产生的坐标，就在哪个平台上继续使用。

工具调用示例

地理编码：  map_geocode(address="北京市朝阳区阜通东大街6号")
逆地理编码：map_reverse_geocode(location="116.481,39.990", platform="amap")
POI 搜索：  map_search_poi(keyword="星巴克", city="上海", limit=10)
周边搜索：  map_search_around(location="116.481,39.990", keyword="地铁站", radius=1000)
路径规划：  map_direction(origin="116.481,39.990", destination="116.434,39.909", mode="driving")
天气查询：  map_weather(city="110000")

典型工作流：先用 map_geocode 把地址转成坐标和 adcode → 再用坐标做路径规划 / 周边搜索，或用 adcode 查天气。

项目结构

mcp-map-server/
├── src/mcp_map_server/
│   ├── server.py                # MCP 服务器入口，工具定义与分发
│   └── platforms/
│       ├── base.py              # 平台抽象层与统一数据模型
│       ├── amap.py              # 高德地图实现
│       └── baidu.py             # 百度地图实现
├── Dockerfile
├── docker-compose.yaml
├── .github/workflows/
│   └── build-release.yaml       # CI/CD 工作流
├── requirements.txt
├── pyproject.toml
└── .env.example

License

MIT