内容
# arcpro-mcp
> 通过 **模型上下文协议（MCP）** 使用自然语言控制 **ArcGIS Pro**。
> 与Cursor、Claude和Codex合作 — 自带LLM，保持数据本地化。
[](https://github.com/qiobn/arcpro-mcp/actions/workflows/ci.yml)
[](LICENSE)
[](https://www.python.org/)
`arcpro-mcp` 让AI代理驱动 **实时ArcGIS Pro会话**：检查项目，探索图层和属性，检查坐标系，（即将支持）运行地理处理和构建布局 — 所有操作都可以通过您最喜欢的MCP客户端的聊天提示完成。
与Esri内置助手不同，该项目是 **开源** 的，可以连接到 **任何LLM**，通过您的MCP客户端，并对您的 **实际打开的会话** 进行操作，而不仅仅是生成代码。
## 架构
ArcGIS Pro托管`arcpy`，而`arcpy.mp.ArcGISProject("CURRENT")`仅在运行应用程序内部有效。因此，MCP服务器（由您的客户端启动的单独进程）通过本地套接字与在ArcGIS Pro的Python窗口中运行的小型 **桥** 进行通信：
```
Cursor / Claude / Codex
│ stdio (MCP)
▼
arcpro-mcp (此软件包，单独进程)
│ TCP套接字，长度前缀JSON (127.0.0.1:18748)
▼
arcpro_bridge.py (在ArcGIS Pro的Python窗口中运行)
│ arcpy / arcpy.mp
▼
ArcGIS Pro (实时会话)
```
设计选择与现有工具的比较：
- **套接字，非文件轮询** — 更低延迟，更干净的大数据帧。
- **分层 + 测试** — `src/`软件包，无依赖桥，pytest，CI。
- **安全性第一** — 默认只读；破坏性工具需要确认；`execute_python` **关闭**，除非显式启用；每个调用都 **审计记录**。
- **优秀的用户体验** — 结构化输出，MCP资源和实时 **图层名称自动补全**。
## 要求
- **ArcGIS Pro 3.x** （提供`arcpy`）
- **Python 3.10+** 用于MCP服务器（`arcgispro-py3` conda环境效果很好）
- 一个MCP客户端：**Cursor**，**Claude Desktop** 或 **Codex**
- [`uv`](https://docs.astral.sh/uv/) 推荐（或普通`pip`）
## 安装
```bash
git clone https://github.com/qiobn/arcpro-mcp
cd arcpro-mcp
uv sync # 或：pip install -e .
```
## 使用
### 1. 在ArcGIS Pro中启动桥
打开ArcGIS Pro并加载一个项目，打开 **Python窗口**，并运行：
```python
exec(open(r"C:/path/to/arcpro-mcp/bridge/arcpro_bridge.py").read())
```
您应该看到 `[ArcPro MCP Bridge] Listening on 127.0.0.1:18748`。
### 2. 配置您的MCP客户端
参见 [`examples/mcp-config.example.json`](examples/mcp-config.example.json)。对于Cursor或Claude Desktop：
```json
{
"mcpServers": {
"arcgis-pro": {
"command": "uv",
"args": ["--directory", "C:/path/to/arcpro-mcp", "run", "arcpro-mcp"]
}
}
}
```
### 3. 与其交互
> "Ping ArcGIS Pro并告诉我项目中有什么。"
> "列出图层，然后显示道路图层的前10行。"
> "C:/data/parcels.shp的坐标系是什么？"
## 工具
**只读**
| 工具 | 描述 |
| --- | --- |
| `ping` | 连接性 + 项目状态 |
| `get_project_info` | 项目路径，默认GDB，地图 |
| `list_directory` | 列出文件（确认加载路径） |
| `describe_data` | 数据类型，几何，范围， **CRS** |
| `list_feature_classes` | 工作区中的要素类 |
| `list_layers` | 活动地图上的图层 |
| `list_fields` | 数据集/图层的字段 |
| `count_features` | 图层的行数 |
| `get_layer_features` | 预览属性行 |
| `get_unique_values` | 字段的独特值 |
| `get_workspace` / `list_layouts` | 检查工作区/布局 |
**写入/修改地图**
| 工具 | 描述 |
| --- | --- |
| `add_vector_layer` / `add_raster_layer` | 将数据添加到地图 |
| `remove_layer` | 删除图层（需要确认） |
| `set_layer_visibility` / `zoom_to_layer` | 切换/导航 |
| `create_map` / `save_project` | 地图和项目管理 |
| `select_by_attribute` / `clear_selection` | 基于SQL的选择 |
| `set_workspace` | 设置默认GP工作区 |
| `run_geoprocessing` | 运行 **任何** ArcPy工具，通过点表示法 |
| `create_layout` / `export_layout` | 构建和导出打印布局（PDF/PNG/...） |
`execute_python`（任意`arcpy`）存在但 **禁用**，除非您在 **两个** 环境中都设置`ARCPRO_MCP_ALLOW_EXEC=1`：客户端环境和ArcGIS Pro环境。
## 配置
| 变量 | 默认值 | 描述 |
| --- | --- | --- |
| `ARCPRO_MCP_HOST` | `127.0.0.1` | 桥接主机 |
| `ARCPRO_MCP_PORT` | `18748` | 桥接端口 |
| `ARCPRO_MCP_TRANSPORT` | `stdio` | `stdio` 或 `streamable-http` |
| `ARCPRO_MCP_ALLOW_EXEC` | _(关闭)_ | 启用 `execute_python` （`1`/`true`） |
| `ARCPRO_MCP_AUDIT_LOG` | `~/.arcpro_mcp/audit.log` | 审计日志路径（空字符串禁用） |
| `ARCPRO_MCP_LOG_LEVEL` | `INFO` | 服务器日志级别 |
## 安全
- 只读工具标注`readOnlyHint`，始终安全。
- 破坏性工具（接下来）需要通过MCP询问确认。
- `execute_python` 是可选的，并且双重限制（客户端 + 桥接）。
- 每个请求的 操作 都追加到审计日志中以供审查/重放。
## 路线图
- [x] v0.1 — 套接字桥接，只读工具，审计日志，CI，测试
- [ ] v0.2 — 写入工具（添加/删除图层，选择，地理处理）带有HITL确认
- [ ] v0.3 — `execute_python` 强化，**反射中间件** （CRS/单位健全性），布局和导出
- [ ] v0.4 — 主线程调度队列 / 可选 **.NET Add-In（QueuedTask）** 实现极其稳定的 `arcpy.mp`
- [ ] v1.0 — 安装程序，多客户端文档，复合工具模式以减少令牌
## 许可证
MIT — 参见 [LICENSE](LICENSE)。
## 致谢
架构灵感来自优秀的
[nkarasiak/qgis-mcp](https://github.com/nkarasiak/qgis-mcp),
[jjsantos01/qgis_mcp](https://github.com/jjsantos01/qgis_mcp),
[geo2004/MCP-ArcGISPro](https://github.com/geo2004/MCP-ArcGISPro)，以及[gdal-mcp](https://github.com/Wayfinder-Foundry/gdal-mcp)中的安全模式。
