ArcGIS Pro Bridge

ArcGIS Pro Bridge MCP Server 是一个给 ArcGIS Pro 用的本地 MCP Server。

它的作用可以直接理解成：

• 让 Trae、Cursor、Claude Desktop 这类支持 MCP 的 AI 客户端，能够读取你本机的 ArcGIS Pro 工程信息
• 让 AI 能在 ArcGIS Pro 自带的 Python 环境中执行 ArcPy
• 尽量减少 GISer 手动折腾 Python 环境的成本

这个项目不是 ArcGIS Pro 插件，也不是双击就能打开的桌面软件。它更像一个“后台桥接服务”，由 AI 客户端按 MCP 方式调用。

它适合做什么

当前版本适合这些场景：

• 读取当前 ArcGIS Pro 工程中的地图和图层
• 检查哪些图层的数据源已经断开
• 读取 .aprx 工程中的布局、地图框和默认地图候选
• 读取 .gdb 的要素类、字段和空间参考
• 让 AI 生成 ArcPy 脚本
• 让 AI 执行 Buffer、Clip、Merge 等 ArcPy 地理处理

它不适合做什么

当前版本不适合直接用于这些场景：

• 对公网开放的远程 GIS 服务
• 无人值守地直接修改生产数据
• 替代 ArcGIS Pro 图形界面
• 当作通用文件管理工具浏览任意本地目录

它的定位是“本机上的 ArcGIS Pro AI 桥接工具”，不是通用桌面助手。

使用前需要准备什么

请先确认：

• 你使用的是 Windows
• 你的电脑已经安装 ArcGIS Pro
• ArcGIS Pro 可以正常启动
• 你的电脑中有 Python 3.11 或更高版本
• 建议安装 uv

最容易误解的地方

这是最重要的一节。

1. MCP 配置里的 JSON 不是命令行命令

README 或 examples/ 目录里提供的 JSON 配置，不是复制到 PowerShell 或 CMD 里直接运行的。

这些 JSON 的正确用途是：

• 粘贴到 Trae 的 MCP 配置界面
• 或写入 Cursor / Claude Desktop 的 MCP 配置文件

如果你把 JSON 直接复制到命令行里运行，是不会按预期工作的。

2. uv run arcgis_mcp_server.py 不是给你长期手动测试 stdout 用的

这条命令的作用是启动一个 stdio 型 MCP Server。

它启动后会一直等待客户端请求，这是正常现象，不是卡死。

正常使用时，一般应由 Trae、Cursor、Claude Desktop 自动拉起它，而不是你手动先开一个终端，再自己写测试脚本去读 stdout。

3. 这个项目主要是 ArcGIS MCP，不是文件系统 MCP

它擅长的问题是：

• ArcGIS 环境是否发现成功
• .aprx 工程里有什么
• .gdb 里有什么
• ArcPy 能不能执行

它不适合用来回答：

• 当前项目目录里有什么文件
• 帮我列出任意本地目录结构

这类需求更适合 shell 或单独的文件系统 MCP。

正确使用流程

建议按下面顺序使用：

1. 获取项目并进入项目目录
2. 运行 uv sync
3. 把 MCP 配置 JSON 填到 Trae / Cursor / Claude Desktop 的 MCP 配置里
4. 重启客户端，或刷新 MCP Server 列表
5. 在聊天中直接让 AI 调用 MCP Tool

不推荐的错误流程

这些做法很容易导致“看起来卡住”：

• 把 MCP 配置 JSON 当成命令行命令去运行
• 手动启动 uv run arcgis_mcp_server.py 后，再自己写 Python 脚本去测试 stdout
• 明明要测试 ArcGIS MCP，却问“当前目录下有哪些文件”
• 没有明确要求 AI 使用 MCP，结果它自己转去走 shell

快速开始

第一步：安装依赖

进入项目目录后，运行 uv sync。

注意：

• arcpy 不会通过 uv 安装
• arcpy 来自 ArcGIS Pro 自带环境
• 本项目会在运行时自动寻找它

第二步：把 MCP 配置加到客户端

重要：配置 JSON 中的 <项目目录> 必须替换为你克隆项目的实际路径，直接复制会导致服务无法启动。

具体可复制配置请看：

• examples/claude-desktop-mcp-config.json（Claude Desktop）
• examples/cursor-mcp-config.json（Cursor / Trae）
• examples/README.md（详细说明）

第三步：重启客户端

无论是 Trae、Cursor 还是 Claude Desktop，配置完成后都建议完全重启一次。

第四步：先做最简单的测试

第一次不要直接让 AI 做复杂分析。

建议先让它只调用：

• ping
• health_check
• doctor

确认 MCP 调用链路和 ArcPy 运行时都正常后，再继续读取工程、GDB 或执行地理处理。

如何接入 Trae

Trae 里最关键的是要理解：

• 你填的是 MCP 配置
• 不是终端命令

正确做法

1. 打开 Trae 的 MCP 配置页面
2. 新增一个本地 MCP Server
3. 把示例 JSON 粘贴到 MCP 配置区域
4. 保存配置
5. 重启 Trae，或者刷新 MCP 列表

可参考：

• examples/cursor-mcp-config.json

如果你的 Trae 已经显示服务名称，并且旁边是绿色勾，通常说明：

• 配置格式基本正确
• Trae 能识别这个 MCP Server

但这还不代表当前这次对话一定已经真正调用了 MCP Tool。

如何接入 Cursor

Cursor 的思路和 Trae 类似，也是把 MCP 配置写入它的 MCP 配置位置，而不是复制到终端。

建议做法：

1. 打开 Cursor 的 MCP 配置入口
2. 新增一个本地 stdio MCP Server
3. 填入示例 JSON
4. 保存并重启 Cursor，或刷新工具列表

可参考：

• examples/cursor-mcp-config.json

如何接入 Claude Desktop

Claude Desktop 通过 MCP 配置文件接入，需要特别注意 Windows 下的 PATH 问题。

推荐方式（使用批处理启动脚本）：

1. 找到 Claude Desktop 的 MCP 配置文件
2. 按 examples/claude-desktop-mcp-config.json 填写，替换 <项目目录> 为实际路径
3. 保存文件
4. 完全退出 Claude Desktop
5. 重新打开 Claude Desktop

为什么推荐用批处理脚本？

Claude Desktop 是 Windows GUI 应用，它的 PATH 环境变量与终端不同。即使你在终端里能跑 uv，Claude Desktop 也可能找不到它。项目根目录的 start-mcp-server.bat 会自动在常见位置查找 uv，并设置正确的工作目录。

备选方式（直接使用 uv）：

如果你已将 uv 所在目录添加到 Windows 系统 PATH（而非仅用户 PATH），也可以参考 examples/cursor-mcp-config.json 使用 uv run 方式。

第一次使用时建议怎么问

第一次测试，建议问题尽量简单、尽量像 ArcGIS 问题，而不是“帮我测试 server”。

推荐顺序：

1. 先调用 ping，确认这次请求真的走到了 MCP Tool
2. 再调用 health_check 或 doctor，确认 ArcGIS Pro Python 和 ArcPy 运行时
3. 再读取当前工程图层
4. 再读取指定 GDB 或 .aprx 工程概览
5. 最后再执行 buffer_features、clip_features 或通用 execute_arcpy_code

更多可直接复制的中文提示词见：

• examples/prompt-examples.md

如何判断 AI 是否真的调用了 MCP

这也是非常关键的一节。

如果 AI 真正调用了 MCP

通常会出现这些特征：

• 直接返回 ping、health_check、doctor、inspect_gdb、inspect_project_context 等结果
• 结果内容明显是 ArcGIS 结构化信息
• 不会自己去写测试脚本
• 不会要求你手动长期开着一个 server 窗口读 stdout

如果 AI 没有真正调用 MCP

通常会出现这些特征：

• 它开始自己写 test_mcp_server.py、inspect_gdb.py 之类的脚本
• 它在终端里手动运行 uv run arcgis_mcp_server.py
• 它尝试自己解析 stdout
• 过程看起来“卡住很久”

如果出现这些现象，通常不是 ArcGIS 真的慢，而是它没有按 MCP 协议去使用这个服务。

推荐给 Trae 的测试提示词

如果你怀疑 Trae 没真正走 MCP，可以直接复制这段话给它：

“不要使用 shell，不要写任何测试脚本，不要手动启动任何 server。只允许使用已经配置好的 MCP 工具。请先调用 ping，再调用 health_check，并把返回结果完整告诉我。如果你没有实际调用 MCP 工具，请明确说明。”

这段提示词的作用，是强制它别绕去 shell 路线。

常见使用场景

你可以这样使用它：

• 先让 AI 读取当前 ArcGIS Pro 工程中的地图、图层和字段
• 让 AI 检查哪些图层断开了数据源
• 让 AI 读取某个 .aprx 工程的布局和地图框
• 让 AI 读取某个 .gdb 的结构
• 让 AI 直接执行常见的 Buffer 和 Clip 分析
• 让 AI 先生成 ArcPy，再由你确认后执行

当前可用 Tool

当前主要 Tool 包括：

• ping
• health_check
• doctor
• detect_arcgis_environment
• execute_arcpy_code
• buffer_features
• clip_features
• build_gis_resource_uri
• list_gis_layers
• inspect_project_context
• inspect_gdb
• generate_sync_plan

当前可用 Resource

当前主要 Resource 包括：

• arcgis://server/status
• arcgis://resources/catalog
• arcgis://project/current/layers
• arcgis://project/current/context
• arcgis://project/{project_ref}/layers
• arcgis://project/{project_ref}/context
• arcgis://gdb/{gdb_ref}/schema

常见问题

0. Claude Desktop 无法连接 / Server 未出现

如果配置完成后 Claude Desktop 没有识别到 MCP Server，或报连接失败，请按顺序排查：

先确认 Server 本身能启动： 在项目目录下打开终端，运行 uv run python arcgis_mcp_server.py，如果不报错且进入等待状态，说明 Server 本身没问题。

检查配置文件中的路径：

• 确认 <项目目录> 已替换为你的实际路径
• 确认路径中的反斜杠正确（JSON 中需写成 \\）
• 确认 start-mcp-server.bat 确实存在于项目根目录

检查 uv 是否对 GUI 应用可见：

• 打开新的 CMD 窗口，运行 where uv
• 如果显示路径在 %USERPROFILE%\\.local\\bin\\ 下，Claude Desktop 很可能找不到它
• 解决方案：使用 cmd /c + 批处理脚本方式配置（见 Claude Desktop 接入章节）

检查 Claude Desktop 日志：

• Claude Desktop 的日志通常位于 %APPDATA%\\Claude Desktop\\logs\\
• 查看最新日志文件中是否有 arcgis-pro-bridge 相关报错

确认配置文件位置正确：

• Claude Desktop 的 MCP 配置文件通常在：%APPDATA%\\Claude Desktop\\claude_desktop_config.json
• 如果文件不存在，需要手动创建

如果以上都检查过仍未解决，请在项目 Issues 中附上 Claude Desktop 日志中的相关错误信息。

1. 找不到 ArcGIS Pro 或找不到 arcpy

请先检查：

• ArcGIS Pro 是否已经安装
• ArcGIS Pro 是否可以正常启动
• 是否先调用过 detect_arcgis_environment

如果仍然失败，可以手动设置环境变量：

• ARCGIS_PRO_PYTHON
• ARCGIS_PRO_INSTALL_DIR

2. 读取不到当前工程

如果 ArcGISProject("CURRENT") 无法附着，这通常是 ArcGIS Pro 当前运行上下文的限制，不一定是程序错误。

这时建议直接传入 .aprx 路径，而不是依赖 CURRENT。

3. 图层数据源断开

常见原因包括：

• 数据路径改变
• 网络盘没有挂载
• GDB 被移动
• SDE 连接不可用

建议先调用：

• list_gis_layers
• inspect_project_context

先把断开的数据源找出来。

4. ArcPy 执行时报锁定错误

常见原因包括：

• 图层正在编辑
• 数据正在被 ArcGIS Pro 占用
• 外部程序正在读写数据

建议先关闭编辑状态，再重试。

5. 处理很慢或超时

可以尝试：

• 缩小处理范围
• 减少一次处理的数据量
• 提高 timeout_seconds

安全提醒

execute_arcpy_code 本质上是“在本机执行代码”。

所以请务必注意：

• 只在你信任的电脑上使用
• 不要直接暴露到公网
• 不要让 AI 未经确认就修改正式数据
• 对重要数据先备份，再执行写操作

更详细说明见：

• SECURITY.md

示例目录

如果你需要直接复制配置或查看完整示例，请看：

• examples/README.md
• examples/cursor-mcp-config.json
• examples/claude-desktop-mcp-config.json
• examples/arcpy-buffer-example.py
• examples/prompt-examples.md

本地校验

项目当前使用这些检查命令：

• uv run ruff check .
• uv run ruff format --check .
• uv run python -m unittest discover -s tests -p "test_*.py"

开源信息

• 许可证：LICENSE
• 更新记录：CHANGELOG.md
• 贡献说明：CONTRIBUTING.md