# 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. 克隆仓库

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

### 3. 本地开发运行

```bash
# 安装依赖
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

```bash
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 触发构建：

```bash
git tag v1.0.0
git push origin v1.0.0
```

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

## MCP 客户端配置

### SSE（远程）

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

### stdio（本地）

```json
{
  "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