Skip to content
Back to search

ArcGIS-Pro-Bridge-MCP-Server

ArcGIS Pro Bridge MCP Server 是一个让 AI 客户端连接本机 ArcGIS Pro 的 MCP Server。

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/sangwxx--arcgis-pro-bridge-mcp-server/badge.svg)](/listings/sangwxx--arcgis-pro-bridge-mcp-server)

HTML

<a href="/listings/sangwxx--arcgis-pro-bridge-mcp-server"><img src="/api/listings/sangwxx--arcgis-pro-bridge-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 409 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # ArcGIS Pro Bridge MCP Server
  2. ArcGIS Pro Bridge MCP Server 是一个给 ArcGIS Pro 用的本地 MCP Server。
  3. 它的作用可以直接理解成:
  4. - 让 Trae、Cursor、Claude Desktop 这类支持 MCP 的 AI 客户端,能够读取你本机的 ArcGIS Pro 工程信息
  5. - 让 AI 能在 ArcGIS Pro 自带的 Python 环境中执行 ArcPy
  6. - 尽量减少 GISer 手动折腾 Python 环境的成本
  7. 这个项目不是 ArcGIS Pro 插件,也不是双击就能打开的桌面软件。它更像一个“后台桥接服务”,由 AI 客户端按 MCP 方式调用。
  8. ## 它适合做什么
  9. 当前版本适合这些场景:
  10. - 读取当前 ArcGIS Pro 工程中的地图和图层
  11. - 检查哪些图层的数据源已经断开
  12. - 读取 `.aprx` 工程中的布局、地图框和默认地图候选
  13. - 读取 `.gdb` 的要素类、字段和空间参考
  14. - 让 AI 生成 ArcPy 脚本
  15. - 让 AI 执行 Buffer、Clip、Merge 等 ArcPy 地理处理
  16. ## 它不适合做什么
  17. 当前版本不适合直接用于这些场景:
  18. - 对公网开放的远程 GIS 服务
  19. - 无人值守地直接修改生产数据
  20. - 替代 ArcGIS Pro 图形界面
  21. - 当作通用文件管理工具浏览任意本地目录
  22. 它的定位是“本机上的 ArcGIS Pro AI 桥接工具”,不是通用桌面助手。
  23. ## 使用前需要准备什么
  24. 请先确认:
  25. - 你使用的是 Windows
  26. - 你的电脑已经安装 ArcGIS Pro
  27. - ArcGIS Pro 可以正常启动
  28. - 你的电脑中有 Python 3.11 或更高版本
  29. - 建议安装 `uv`
  30. ## 最容易误解的地方
  31. 这是最重要的一节。
  32. ### 1. MCP 配置里的 JSON 不是命令行命令
  33. README 或 `examples/` 目录里提供的 JSON 配置,不是复制到 PowerShell 或 CMD 里直接运行的。
  34. 这些 JSON 的正确用途是:
  35. - 粘贴到 Trae 的 MCP 配置界面
  36. - 或写入 Cursor / Claude Desktop 的 MCP 配置文件
  37. 如果你把 JSON 直接复制到命令行里运行,是不会按预期工作的。
  38. ### 2. `uv run arcgis_mcp_server.py` 不是给你长期手动测试 stdout 用的
  39. 这条命令的作用是启动一个 `stdio` 型 MCP Server。
  40. 它启动后会一直等待客户端请求,这是正常现象,不是卡死。
  41. 正常使用时,一般应由 Trae、Cursor、Claude Desktop 自动拉起它,而不是你手动先开一个终端,再自己写测试脚本去读 stdout。
  42. ### 3. 这个项目主要是 ArcGIS MCP,不是文件系统 MCP
  43. 它擅长的问题是:
  44. - ArcGIS 环境是否发现成功
  45. - `.aprx` 工程里有什么
  46. - `.gdb` 里有什么
  47. - ArcPy 能不能执行
  48. 它不适合用来回答:
  49. - 当前项目目录里有什么文件
  50. - 帮我列出任意本地目录结构
  51. 这类需求更适合 shell 或单独的文件系统 MCP。
  52. ## 正确使用流程
  53. 建议按下面顺序使用:
  54. 1. 获取项目并进入项目目录
  55. 2. 运行 `uv sync`
  56. 3. 把 MCP 配置 JSON 填到 Trae / Cursor / Claude Desktop 的 MCP 配置里
  57. 4. 重启客户端,或刷新 MCP Server 列表
  58. 5. 在聊天中直接让 AI 调用 MCP Tool
  59. ## 不推荐的错误流程
  60. 这些做法很容易导致“看起来卡住”:
  61. - 把 MCP 配置 JSON 当成命令行命令去运行
  62. - 手动启动 `uv run arcgis_mcp_server.py` 后,再自己写 Python 脚本去测试 stdout
  63. - 明明要测试 ArcGIS MCP,却问“当前目录下有哪些文件”
  64. - 没有明确要求 AI 使用 MCP,结果它自己转去走 shell
  65. ## 快速开始
  66. ### 第一步:安装依赖
  67. 进入项目目录后,运行 `uv sync`。
  68. 注意:
  69. - `arcpy` 不会通过 `uv` 安装
  70. - `arcpy` 来自 ArcGIS Pro 自带环境
  71. - 本项目会在运行时自动寻找它
  72. ### 第二步:把 MCP 配置加到客户端
  73. **重要**:配置 JSON 中的 `<项目目录>` 必须替换为你克隆项目的实际路径,直接复制会导致服务无法启动。
  74. 具体可复制配置请看:
  75. - [examples/claude-desktop-mcp-config.json](examples/claude-desktop-mcp-config.json)(Claude Desktop)
  76. - [examples/cursor-mcp-config.json](examples/cursor-mcp-config.json)(Cursor / Trae)
  77. - [examples/README.md](examples/README.md)(详细说明)
  78. ### 第三步:重启客户端
  79. 无论是 Trae、Cursor 还是 Claude Desktop,配置完成后都建议完全重启一次。
  80. ### 第四步:先做最简单的测试
  81. 第一次不要直接让 AI 做复杂分析。
  82. 建议先让它只调用:
  83. - `ping`
  84. - `health_check`
  85. - `doctor`
  86. 确认 MCP 调用链路和 ArcPy 运行时都正常后,再继续读取工程、GDB 或执行地理处理。
  87. ## 如何接入 Trae
  88. Trae 里最关键的是要理解:
  89. - 你填的是 MCP 配置
  90. - 不是终端命令
  91. ### 正确做法
  92. 1. 打开 Trae 的 MCP 配置页面
  93. 2. 新增一个本地 MCP Server
  94. 3. 把示例 JSON 粘贴到 MCP 配置区域
  95. 4. 保存配置
  96. 5. 重启 Trae,或者刷新 MCP 列表
  97. 可参考:
  98. - [examples/cursor-mcp-config.json](examples/cursor-mcp-config.json)
  99. 如果你的 Trae 已经显示服务名称,并且旁边是绿色勾,通常说明:
  100. - 配置格式基本正确
  101. - Trae 能识别这个 MCP Server
  102. 但这还不代表当前这次对话一定已经真正调用了 MCP Tool。
  103. ## 如何接入 Cursor
  104. Cursor 的思路和 Trae 类似,也是把 MCP 配置写入它的 MCP 配置位置,而不是复制到终端。
  105. 建议做法:
  106. 1. 打开 Cursor 的 MCP 配置入口
  107. 2. 新增一个本地 `stdio` MCP Server
  108. 3. 填入示例 JSON
  109. 4. 保存并重启 Cursor,或刷新工具列表
  110. 可参考:
  111. - [examples/cursor-mcp-config.json](examples/cursor-mcp-config.json)
  112. ## 如何接入 Claude Desktop
  113. Claude Desktop 通过 MCP 配置文件接入,需要特别注意 Windows 下的 PATH 问题。
  114. **推荐方式(使用批处理启动脚本):**
  115. 1. 找到 Claude Desktop 的 MCP 配置文件
  116. 2. 按 [examples/claude-desktop-mcp-config.json](examples/claude-desktop-mcp-config.json) 填写,**替换 `<项目目录>` 为实际路径**
  117. 3. 保存文件
  118. 4. 完全退出 Claude Desktop
  119. 5. 重新打开 Claude Desktop
  120. **为什么推荐用批处理脚本?**
  121. Claude Desktop 是 Windows GUI 应用,它的 PATH 环境变量与终端不同。即使你在终端里能跑 `uv`,Claude Desktop 也可能找不到它。项目根目录的 `start-mcp-server.bat` 会自动在常见位置查找 `uv`,并设置正确的工作目录。
  122. **备选方式(直接使用 uv):**
  123. 如果你已将 `uv` 所在目录添加到 Windows 系统 PATH(而非仅用户 PATH),也可以参考 [examples/cursor-mcp-config.json](examples/cursor-mcp-config.json) 使用 `uv run` 方式。
  124. ## 第一次使用时建议怎么问
  125. 第一次测试,建议问题尽量简单、尽量像 ArcGIS 问题,而不是“帮我测试 server”。
  126. 推荐顺序:
  127. 1. 先调用 `ping`,确认这次请求真的走到了 MCP Tool
  128. 2. 再调用 `health_check` 或 `doctor`,确认 ArcGIS Pro Python 和 ArcPy 运行时
  129. 3. 再读取当前工程图层
  130. 4. 再读取指定 GDB 或 `.aprx` 工程概览
  131. 5. 最后再执行 `buffer_features`、`clip_features` 或通用 `execute_arcpy_code`
  132. 更多可直接复制的中文提示词见:
  133. - [examples/prompt-examples.md](examples/prompt-examples.md)
  134. ## 如何判断 AI 是否真的调用了 MCP
  135. 这也是非常关键的一节。
  136. ### 如果 AI 真正调用了 MCP
  137. 通常会出现这些特征:
  138. - 直接返回 `ping`、`health_check`、`doctor`、`inspect_gdb`、`inspect_project_context` 等结果
  139. - 结果内容明显是 ArcGIS 结构化信息
  140. - 不会自己去写测试脚本
  141. - 不会要求你手动长期开着一个 server 窗口读 stdout
  142. ### 如果 AI 没有真正调用 MCP
  143. 通常会出现这些特征:
  144. - 它开始自己写 `test_mcp_server.py`、`inspect_gdb.py` 之类的脚本
  145. - 它在终端里手动运行 `uv run arcgis_mcp_server.py`
  146. - 它尝试自己解析 stdout
  147. - 过程看起来“卡住很久”
  148. 如果出现这些现象,通常不是 ArcGIS 真的慢,而是它没有按 MCP 协议去使用这个服务。
  149. ## 推荐给 Trae 的测试提示词
  150. 如果你怀疑 Trae 没真正走 MCP,可以直接复制这段话给它:
  151. “不要使用 shell,不要写任何测试脚本,不要手动启动任何 server。只允许使用已经配置好的 MCP 工具。请先调用 `ping`,再调用 `health_check`,并把返回结果完整告诉我。如果你没有实际调用 MCP 工具,请明确说明。”
  152. 这段提示词的作用,是强制它别绕去 shell 路线。
  153. ## 常见使用场景
  154. 你可以这样使用它:
  155. - 先让 AI 读取当前 ArcGIS Pro 工程中的地图、图层和字段
  156. - 让 AI 检查哪些图层断开了数据源
  157. - 让 AI 读取某个 `.aprx` 工程的布局和地图框
  158. - 让 AI 读取某个 `.gdb` 的结构
  159. - 让 AI 直接执行常见的 Buffer 和 Clip 分析
  160. - 让 AI 先生成 ArcPy,再由你确认后执行
  161. ## 当前可用 Tool
  162. 当前主要 Tool 包括:
  163. - `ping`
  164. - `health_check`
  165. - `doctor`
  166. - `detect_arcgis_environment`
  167. - `execute_arcpy_code`
  168. - `buffer_features`
  169. - `clip_features`
  170. - `build_gis_resource_uri`
  171. - `list_gis_layers`
  172. - `inspect_project_context`
  173. - `inspect_gdb`
  174. - `generate_sync_plan`
  175. ## 当前可用 Resource
  176. 当前主要 Resource 包括:
  177. - `arcgis://server/status`
  178. - `arcgis://resources/catalog`
  179. - `arcgis://project/current/layers`
  180. - `arcgis://project/current/context`
  181. - `arcgis://project/{project_ref}/layers`
  182. - `arcgis://project/{project_ref}/context`
  183. - `arcgis://gdb/{gdb_ref}/schema`
  184. ## 常见问题
  185. ### 0. Claude Desktop 无法连接 / Server 未出现
  186. 如果配置完成后 Claude Desktop 没有识别到 MCP Server,或报连接失败,请按顺序排查:
  187. **先确认 Server 本身能启动:**
  188. 在项目目录下打开终端,运行 `uv run python arcgis_mcp_server.py`,如果不报错且进入等待状态,说明 Server 本身没问题。
  189. **检查配置文件中的路径:**
  190. - 确认 `<项目目录>` 已替换为你的实际路径
  191. - 确认路径中的反斜杠正确(JSON 中需写成 `\\`)
  192. - 确认 `start-mcp-server.bat` 确实存在于项目根目录
  193. **检查 uv 是否对 GUI 应用可见:**
  194. - 打开新的 CMD 窗口,运行 `where uv`
  195. - 如果显示路径在 `%USERPROFILE%\\.local\\bin\\` 下,Claude Desktop 很可能找不到它
  196. - 解决方案:使用 `cmd /c` + 批处理脚本方式配置(见 Claude Desktop 接入章节)
  197. **检查 Claude Desktop 日志:**
  198. - Claude Desktop 的日志通常位于 `%APPDATA%\\Claude Desktop\\logs\\`
  199. - 查看最新日志文件中是否有 `arcgis-pro-bridge` 相关报错
  200. **确认配置文件位置正确:**
  201. - Claude Desktop 的 MCP 配置文件通常在:`%APPDATA%\\Claude Desktop\\claude_desktop_config.json`
  202. - 如果文件不存在,需要手动创建
  203. 如果以上都检查过仍未解决,请在项目 Issues 中附上 Claude Desktop 日志中的相关错误信息。
  204. ### 1. 找不到 ArcGIS Pro 或找不到 arcpy
  205. 请先检查:
  206. - ArcGIS Pro 是否已经安装
  207. - ArcGIS Pro 是否可以正常启动
  208. - 是否先调用过 `detect_arcgis_environment`
  209. 如果仍然失败,可以手动设置环境变量:
  210. - `ARCGIS_PRO_PYTHON`
  211. - `ARCGIS_PRO_INSTALL_DIR`
  212. ### 2. 读取不到当前工程
  213. 如果 `ArcGISProject("CURRENT")` 无法附着,这通常是 ArcGIS Pro 当前运行上下文的限制,不一定是程序错误。
  214. 这时建议直接传入 `.aprx` 路径,而不是依赖 `CURRENT`。
  215. ### 3. 图层数据源断开
  216. 常见原因包括:
  217. - 数据路径改变
  218. - 网络盘没有挂载
  219. - GDB 被移动
  220. - SDE 连接不可用
  221. 建议先调用:
  222. - `list_gis_layers`
  223. - `inspect_project_context`
  224. 先把断开的数据源找出来。
  225. ### 4. ArcPy 执行时报锁定错误
  226. 常见原因包括:
  227. - 图层正在编辑
  228. - 数据正在被 ArcGIS Pro 占用
  229. - 外部程序正在读写数据
  230. 建议先关闭编辑状态,再重试。
  231. ### 5. 处理很慢或超时
  232. 可以尝试:
  233. - 缩小处理范围
  234. - 减少一次处理的数据量
  235. - 提高 `timeout_seconds`
  236. ## 安全提醒
  237. `execute_arcpy_code` 本质上是“在本机执行代码”。
  238. 所以请务必注意:
  239. - 只在你信任的电脑上使用
  240. - 不要直接暴露到公网
  241. - 不要让 AI 未经确认就修改正式数据
  242. - 对重要数据先备份,再执行写操作
  243. 更详细说明见:
  244. - [SECURITY.md](SECURITY.md)
  245. ## 示例目录
  246. 如果你需要直接复制配置或查看完整示例,请看:
  247. - [examples/README.md](examples/README.md)
  248. - [examples/cursor-mcp-config.json](examples/cursor-mcp-config.json)
  249. - [examples/claude-desktop-mcp-config.json](examples/claude-desktop-mcp-config.json)
  250. - [examples/arcpy-buffer-example.py](examples/arcpy-buffer-example.py)
  251. - [examples/prompt-examples.md](examples/prompt-examples.md)
  252. ## 本地校验
  253. 项目当前使用这些检查命令:
  254. - `uv run ruff check .`
  255. - `uv run ruff format --check .`
  256. - `uv run python -m unittest discover -s tests -p "test_*.py"`
  257. ## 开源信息
  258. - 许可证:[LICENSE](LICENSE)
  259. - 更新记录:[CHANGELOG.md](CHANGELOG.md)
  260. - 贡献说明:[CONTRIBUTING.md](CONTRIBUTING.md)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.