Skip to main content
Glama
Sign In
mcp-map-server

mcp-map-server

by ganyu123456
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

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 的坐标顺序差异

Related MCP server: Amap MCP Server

快速开始

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

Available Tools

9 tools
map_directionA

路径规划：计算两点间的路线，支持驾车(driving)、步行(walking)、公交(transit)、骑行(riding)。返回总距离、总时长和分段导航。起终点为'经度,纬度'坐标。

Inputs: origin (required), destination (required), city, mode, +1 more.

map_distanceB

距离测量：计算两点间的距离和预计耗时。mode 为 driving（驾车）或 walking（步行）。起终点为'经度,纬度'坐标。

Inputs: origin (required), destination (required), mode, platform.

map_geocodeB

地理编码：将结构化地址（如'北京市朝阳区阜通东大街6号'）转换为经纬度坐标。返回坐标、行政区划和 adcode（可用于天气查询）。

Inputs: address (required), city, platform.

map_get_platform_statusA

查询各地图平台的启用与可用状态（是否已配置 API Key）。

Inputs: no named parameters.

map_ip_locationA

IP 定位：根据 IP 地址返回其大致所在的省市。留空则定位请求来源 IP。

Inputs: ip, platform.

map_reverse_geocodeA

逆地理编码：将经纬度坐标转换为可读地址。坐标格式为'经度,纬度'（如'116.481,39.990'）。注意坐标与平台绑定：高德为 GCJ-02，百度为 BD-09，不可跨平台混用。

Inputs: location (required), platform.

map_search_aroundA

周边搜索：以某坐标为中心，在指定半径内搜索 POI（如附近的餐厅、地铁站）。坐标格式'经度,纬度'。

Inputs: location (required), limit, radius, keyword, +1 more.

map_search_poiA

关键字 POI 搜索：按关键字搜索地点（如'星巴克'、'医院'），可限定城市。返回名称、地址、坐标、电话等。

Inputs: keyword (required), city, page, limit, +1 more.

map_weatherA

天气查询：查询某行政区的实时天气与未来几日预报。city 参数需传行政区划编码 adcode（可先用 map_geocode 获取）。

Inputs: city (required), platform.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.9/5.0

    Scored across 9 tools

    Disambiguation5/5

    Each tool targets a distinct mapping operation: route planning, distance, geocoding, reverse geocoding, POI search, nearby search, IP location, weather, and platform status. No overlapping purposes; agents can clearly distinguish them.

    Naming Consistency4/5

    All tools share the 'map_' prefix and use underscores, but the verb-noun pattern is not uniform (e.g., 'map_direction' vs 'map_get_platform_status'). Minor inconsistency, but still predictable.

    Tool Count5/5

    9 tools cover the core mapping domain well: geocoding, routing, POI search, weather, etc. Not too many or too few; each tool serves a clear purpose.

    Completeness5/5

    The tool set covers essential mapping functionalities including geocoding, reverse geocoding, routing, distance, POI search, nearby search, IP location, and weather. No obvious gaps.

    Maintenance

    ActivityNo data
    ResponsivenessSyncing

    Resources

    Related MCP Connectors

    Related MCP Servers