关于 ArcGIS MCP Bridge
ArcGIS MCP Bridge 是一个本地优先的 MCP 服务,向 LLM Agent 暴露 100 个 ArcGIS Pro / ArcPy 地理处理工具。它采用双进程架构,并通过 PathGuard 限制文件系统访问、对破坏性操作设置确认门槛,适合 Windows 上持有 ArcGIS Pro 许可的 GIS 用户。
主要功能
- 01100 个声明式地理处理工具
- 02Layer A 与 Layer B 双进程隔离
- 03PathGuard 文件系统沙箱
- 04破坏性操作需 confirm 参数确认
- 05基于 JSON-RPC 2.0 的 stdio 传输
适用场景
- 01通过自然语言执行缓冲区分析、融合和栅格计算
- 02在 ArcGIS Pro 中批量检查和修复几何数据
- 03将手绘地块草图配准后提交到地理数据库
MCP 相关
该项目是一个 MCP 服务,通过 stdio JSON-RPC 向 Claude Desktop 等 MCP 主机暴露 ArcPy 地理处理工具。
配置
本地服务的配置在各客户端中通用,复制后粘贴到客户端的 MCP 配置文件即可。
uvx arcgis-mcp-bridgeARCPY_PYTHON_PATHPath to the licensed ArcGIS Pro Python interpreter or cloned arcgis-mcp-env interpreter.ARCGIS_MCP_ALLOWED_ROOTSOptional semicolon-separated PathGuard boundary roots for local GIS data.ARCGIS_MCP_SCRATCH_GDBOptional default output workspace. If set, it must point to an existing file geodatabase.ARCGIS_MCP_MAX_WORKERSOptional maximum number of concurrent ArcPy worker subprocesses. Defaults to 2.本地服务需要在你的电脑上安装运行环境(如 Node.js 18+)。各客户端的配置文件位置不同,请参考客户端文档。
工具
本地服务需要在你的电脑上运行后才能读取工具,维护者暂未提供工具列表。
详细介绍
arcgis-mcp-bridge
快速开始
arcgis-mcp-bridge 需要 Windows、已授权的 ArcGIS Pro 安装,以及
Python 3.11 或更高版本来运行桥接包。
使用一个包管理器安装引导包:
# Option A — pip
py -m pip install --upgrade arcgis-mcp-bridge
# Option B — uv
uv pip install --upgrade arcgis-mcp-bridge
然后克隆 ArcGIS Pro 的 Python 环境:
# The final JSON report contains the target `python_exe` path.
py -m arcgis_mcp.setup_env
如果已安装的控制台命令可通过 PATH 使用,
arcgis-mcp-setup 等同于 py -m arcgis_mcp.setup_env。
**适用于安装了多个 Python 的 Windows 系统的重要说明:**只有将
arcgis-mcp-bridge安装到报告的arcgis-mcp-env\python.exe中, 安装配置才算完成。MCP 服务的command和ARCPY_PYTHON_PATH必须使用同一个解释器。这可以避免因从其他 Python 环境加载包或本机扩展而导致的工作进程故障。
完整的安装与配置步骤请参阅 05 — 安装。
100 个声明式地理处理工具。两个隔离进程。一条安全底线。
一款安全、本地优先的异步 MCP 服务,通过 stdio JSON-RPC 向 Claude Desktop 和其他 MCP 主机开放 ArcGIS Pro 的 ArcPy 引擎。
技术文章:为 ArcGIS Pro 和 ArcPy 构建安全的 MCP 桥接
| 工具目录 | 100 个工具 · 10 个垂直领域 |
| 测试 | 86 个单元测试 · 86/86 通过 · arcpy 已模拟 |
| 真实运行时证据 | 可复现的 ArcGIS Pro MCP 冒烟基准测试 |
| 静态分析 | Ruff 检查通过 · Mypy strict 检查通过 |
| 传输 | 基于 stdio 的 JSON-RPC 2.0 |
| 许可证 | Apache-2.0 |
为什么选择 arcgis-mcp-bridge?
| 特性 | arcgis-mcp-bridge | geo2004/MCP-ArcGISPro | nicogis (C#/.NET) |
|---|---|---|---|
| 工具 | 100 | ~15 | ~10 |
| 依赖同步 | 确定性(uv.lock) | 命令式(requirements.txt) | 原生 NuGet |
| 传输 | stdio JSON-RPC | 基于文件的 IPC | 命名管道 |
| 安全架构 | 已记录的 PathGuard 沙箱 | 未指定 / 默认主机访问权限 | 未指定 / 默认主机访问权限 |
| arcpy 隔离 | 双进程架构 | 单进程执行 | 插件进程内执行 |
| CI(离线验证) | ✅ 支持 | ❌ 不支持 | ❌ 不支持 |
| 许可证 | Apache-2.0 | MIT | MIT |
亮点:草图 → GIS 工作流
手绘地块边界 → 照片 → 地理数据库要素类。 ORB+RANSAC 图像配准、HSV 墨迹分割、直接提交到 GDB。 无需手动数字化。
**演示即将推出。**预览草图转 GIS 工作流:
- 在纸上画一个多边形并拍照。
- 向 Claude 提问:“使用 extract_sketch_to_gis 将此照片与我的底图配准, 并将结果提交到我的 GDB。”
- 要素类会显示在 ArcGIS Pro 中——无需手动数字化。
00 — 示例提示词
health_check 成功后,可以自然地与 Claude 对话:
"Buffer all parcels in my GDB by 50 meters and save to scratch."
"List all feature classes in C:\GIS\city.gdb starting with 'road_'."
"Dissolve the neighborhoods layer by district_id."
"Run kernel density on crime_points with a 500-meter search radius."
"Calculate slope and aspect from the DEM at C:\GIS\dem.tif."
"Find the 3 nearest facilities to each incident in my network dataset."
"Check geometry on all feature classes in my GDB and repair errors."
01 — 核心架构与理念
flowchart TD
A[Claude Desktop / Cursor] -->|JSON-RPC over stdio| B[Layer A · MCP Protocol Host]
B -->|NDJSON subprocess bridge| C[Layer B · ArcPy Worker]
C --> D[ArcGIS Pro / ArcPy Runtime]
A 层 — 异步事件驱动服务器(arcgis_mcp/server.py)。
在桥接解释器上运行 FastMCP。负责 stdio 通道,根据冻结的 Pydantic v2 契约验证每个请求,并通过 asyncio.create_subprocess_exec 分派任务——事件循环不会因地理处理调用而阻塞,也不会持有线程锁。A 层不包含任何模块级 arcpy 或 cv2 导入(已通过审计门禁中的 grep 验证);它不会触及 Esri 原生代码,因此不会因此崩溃。
B 层 — ArcPy 子进程隔离工作器(arcgis_mcp/worker.py)。
每个任务都会在获得许可的 ArcGIS Pro 解释器(ARCPY_PYTHON_PATH)上启动一个工作器。只有这里允许 import arcpy;cv2 会在唯一需要它的视觉工具中延迟加载。工作器启动时会将 stdout 重定向到 stderr——唯一获准写入 stdout 的内容是最终的 NDJSON 结果帧,因此原生 ArcObjects 输出绝不会破坏 JSON-RPC 通道。原生崩溃会终止工作器,而不是服务器:父进程会将非零退出码转换为结构化错误帧。
声明式注册表(arcgis_mcp/registry.py)。
每个工具都是一个 ToolSpec(name, category, description, input_model, worker_fn, destructive)。一个通用代理工厂会在 A 层生成目录中的全部 100 个 MCP 端点;一个通用的 run_tool 分派器会在 B 层为它们提供服务。除目录工具外,还会公开三个核心端点:health_check、list_layers 和 execute_spatial_tool。添加目录工具 #101 只需修改两个文件——无需改动运行时循环。
每个跨越进程边界的故障都会分类为:
validation · security · not_found(输入路径不存在;消息会指出字段和路径)· license · geoprocessing(包含完整的 arcpy.GetMessages() 堆栈;对于 Describe 等非地理处理调用,则包含 ArcPy 自身的消息)· internal(异常类型和消息;回溯信息保留在服务器日志中)。
02 — 100 种工具分类矩阵
| # | 领域 | 工具数 | 主要能力 |
|---|---|---|---|
| 1 | map_layer_management | 10 | .aprx 地图、图层顺序/可见性/符号系统、相机、保存 |
| 2 | data_management | 22 | 要素类/地理数据库生命周期、字段、Describe、Excel/GeoJSON/CSV 交换 |
| 3 | geometry_analysis | 23 | 叠加分析、融合/合并、选择、连接、邻近分析、渔网 |
| 4 | coordinate_reference_projection | 4 | 基于 WKID 定义/投影矢量数据和栅格数据、CRS 查询 |
| 5 | raster_operations | 15 | 地图代数、分区统计、DEM 坡度/坡向/山体阴影、水文分析 |
| 6 | vision_analytics | 1 | 草图转 GIS:ORB+RANSAC 配准 → HSV 墨迹 → 提交到 GDB |
| 7 | export_layout | 9 | PDF/PNG 图件、DPI 控制、地图框、文本/图例、页面尺寸 |
| 8 | editing_topology | 7 | 修复/检查几何、追加、去重、差异比较、拓扑验证 |
| 9 | network_analysis | 4 | 服务区、路径规划、起讫点成本矩阵、最近设施 |
| 10 | spatial_statistics | 5 | 平均中心、标准差椭圆、核密度、Gi* 热点、Moran's I |
| 总计 | 100 |
Esri 扩展许可(Spatial、Network)通过一个共享上下文管理器管理,并在正常的 Python 异常路径中通过 finally 归还。工作器进程隔离会将原生故障限制在当前任务内;许可不可用时会返回结构化错误帧,而不会终止 MCP 服务。
破坏性变更安全底线
十个会变更状态的工具在未提供显式
confirm: true 载荷令牌时拒绝运行。此检查在调度器中触发,早于
支付 10–30 s 的 arcpy 导入开销;注册表也会拒绝注册契约中缺少
confirm 字段的破坏性规格:
append_features calculate_field define_projection
delete_dataset delete_field delete_identical
extract_sketch_to_gis near_analysis remove_layer_from_map
repair_geometry
calculate_field 还设有额外的表达式通道安全底线:默认的
expression_type 为 ARCADE(Esri 的沙盒表达式语言),而
PYTHON3 — 会在工作进程内执行代码 — 若未显式提供 confirm: true,则会在 Layer-A 契约边界被拒绝。raster_calculator 表达式受契约验证器约束,只允许纯地图代数语法(标识符、数字、运算符;不允许引号或双下划线访问)。
03 — 自动化质量门禁与测试
需授权运行时的证据在
benchmarks/ 方法卡中单独报告。其中提交的结果使用真实的 ArcGIS Pro 工作进程和专用临时 GDB;它不会与模拟单元测试数量合并,也不会被当作对全部 100 个地理处理工具的验证。
明确说明范围: 当前自动化门禁包含 86 项单元测试,覆盖 PathGuard 边界、Pydantic 契约、通用注册表中的路径防护与注册不变量、工作进程的错误边界映射,以及 Settings 环境验证。它会测试目录的结构契约和每个安全关键接合点,但不声称对 100 个地理处理工具本身进行多场景验证;这些工具需在授权的 ArcGIS 运行时中执行,而 CI 运行器均不具备该运行时。
内存测试架构。 tests/conftest.py 会在任何软件包导入解析前,向
sys.modules["arcpy"] 和 sys.modules["arcpy.sa"] 注入 MagicMock
代理(其中 CheckExtension 返回 "Available")。整个测试套件在不到一秒内执行完毕,无需安装 ArcGIS、无需检出许可证,也无需 Esri 运行时;本地和 CI 环境的行为完全一致。
测试范围。
tests/test_security.py和tests/test_pathguard.py— PathGuard 边界防火墙,使用 pytest 的tmp_pathfixture 在真实目录上进行测试:沙盒内的有效读取/写入会通过;路径遍历(..段)、UNC、相对路径、NUL 字节、保留设备名、超长路径和根目录外路径会被拒绝;写入规则(ArcGIS 数据集名称规则、显式启用覆盖)会得到执行。tests/test_contracts.py— Pydantic 契约强制执行:逐工具参数规格、跨字段验证器、frozen/extra="forbid",以及 IPC 信封的ok异或error不变量。tests/test_registry.py和tests/test_registry_guard.py— 注册表流完整性,以及通用的apply_path_guard强制执行与register不变量 — 每个 schema 都必须是ToolInput子类,每个path_fields条目都必须引用有效角色,拒绝重复名称,且每个破坏性规格都必须带有confirm门禁。tests/test_worker.py—process_frame错误边界映射:每种故障类别(验证、安全、许可证、地理处理、内部错误)都会映射到各自不同的WorkerError.kind。tests/test_config.py—Settings.from_environment验证:必需变量、目录/文件检查、整数范围,以及缺少临时地理数据库时快速失败。
注册表测试中的副作用导入 import arcgis_mcp.tools 用于填充目录;它带有 # noqa 标记,确保不会再被任何 linter 移除。
静态分析。 Ruff 在 88 列宽下,以 py311 为最低版本(代码必须能在最早支持的解释器上解析 — Layer B),强制执行规范格式以及
E/W/F/I/B/RUF 规则。土耳其语注释受到一等支持:无点的 ı/İ 已登记在
allowed-confusables 中,因此配置会兼容这些文本,而不会重写它们。
Mypy 会通过 Pydantic 插件,对全部 31 个源文件运行 strict = true。
make format # ruff format + import sorting (mutates)
make lint # ruff check, mutates nothing
make type-check # mypy --strict over arcgis_mcp/
make security-audit # live registry inspection: path roles + confirm gates
make verify-all # lint + type-check + security-audit, one gate
python -m pytest # 86/86
04 — 安全框架(PathGuard Sandbox)
每个契约中的每个文件系统参数都会在模型的 path_fields
映射中声明其角色——"read"、"write" 或 "read_list"。一个共享的强制执行函数会在
两个进程中应用这些声明:Layer A 在启动工作进程前进行预检;
Layer B 则会重新验证,因为它从不信任其父进程。
两项边界控制:
validate_read(raw: str)— 完整解析路径(在进行任何比较之前,先解析符号链接、..并折叠相对路径段),并要求路径位于配置的allowed_roots目录内。通过 最深已存在前缀解析策略强制要求路径存在:目标路径或其可由文件系统解析的地理数据库前缀必须 存在。这使 GDB 内部数据集 (…\city.gdb\roads)成为一等对象——.gdb容器会在文件系统上进行验证,而逻辑尾部 则仅限于纯数据集名称,只有 arcpy 才能解析这些名称。validate_write(raw: str, *, overwrite: bool)— 同样进行解析和路径包含性验证, 另加符合 ArcGIS 规则的数据集命名以及覆盖规范:除非请求 明确设置overwrite: true,否则绝不会替换现有目标。
任何逃逸模式——路径遍历序列、UNC 共享、NUL 字节、保留设备名称、根目录之外的目标——都会立即引发
PathSecurityError:请求会收到结构化的 security 帧,且绝不会为其编排子进程。
05 — 📦 安装
选择符合你使用场景的上手方式。
前置条件
- Windows,以及已授权的 ArcGIS Pro 安装
arcgis-mcp-bridge需要 Python 3.11 或更高版本ARCGIS_MCP_ALLOWED_ROOTS指定的目录必须已存在且可写ARCGIS_MCP_SCRATCH_GDB指定的文件地理数据库必须已存在,除非<first allowed root>\scratch.gdb已存在
路径 A:纯 PyPI 安装 — 推荐 Windows 用户使用
这是为 Claude Desktop 和其他 Windows 上的 MCP 主机提供的最简单、最可靠的配置。推荐的配置让 Layer A(MCP 服务)和 Layer B(ArcPy 工作进程)都使用同一个
arcgis-mcp-env\python.exe。
选择一条引导安装命令:
# Option A — pip
py -m pip install --upgrade arcgis-mcp-bridge
# Option B — uv
uv pip install --upgrade arcgis-mcp-bridge
然后克隆 ArcGIS Pro 的 Python 环境:
# The final JSON report contains the target `python_exe` path.
py -m arcgis_mcp.setup_env
如果已安装的控制台命令可通过 PATH 使用,
arcgis-mcp-setup 等同于 py -m arcgis_mcp.setup_env。
从 JSON 报告中复制 python_exe 的值,并在下方赋值:
$ArcGISMcpPython = "C:\...\envs\arcgis-mcp-env\python.exe"
选择一条安装命令:
# Standard installation
& $ArcGISMcpPython -m pip install --upgrade arcgis-mcp-bridge
# OR: include the optional OpenCV-based sketch-to-GIS extension
& $ArcGISMcpPython -m pip install --upgrade "arcgis-mcp-bridge[vision]"
不要同时运行两条命令;第二条命令已将标准包和
vision 扩展一并安装。
将 $ArcGISMcpPython 同时用作 MCP 服务解释器和
ARCPY_PYTHON_PATH。这样可以避免从其他 Python
安装中解析 arcgis_mcp、Pydantic、pydantic-core
及其他原生依赖项。
路径 B:Git 克隆与确定性开发 — GIS 贡献者
此方式让 Layer A 保持在独立的开发环境中,同时在单独克隆且已授权的
arcgis-mcp-env 工作进程中运行 ArcPy 操作。
# 1. Clone the repository.
git clone https://github.com/muend/arcgis-mcp-bridge.git
cd arcgis-mcp-bridge
# 2. Create the isolated development environment.
# Do not use --system-site-packages: Layer A must remain independent of arcpy.
uv venv --python "C:\Program Files\ArcGIS\Pro\bin\Python\envs\arcgispro-py3\python.exe"
# 3. Synchronize the committed dependency resolution.
uv sync --locked
选择一条工作进程配置命令:
# Standard worker
uv run python -m arcgis_mcp.setup_env --install-runtime-deps --project-root .
# OR: worker with the optional OpenCV-based sketch-to-GIS extension
uv run python -m arcgis_mcp.setup_env --with-vision --project-root .
--with-vision 会隐含安装运行时依赖,因此不应连续运行这两条命令。
设置命令是幂等的,接受 --env-name(默认值:
arcgis-mcp-env)和 --dry-run,并输出 JSON 报告。如果 ArcGIS Pro 的
conda.exe 无法通过 PATH 使用,请设置
ARCGIS_CONDA_EXE。
工作器解释器完整性
Layer B 的启动方式如下:
ARCPY_PYTHON_PATH -m arcgis_mcp.worker
ARCPY_PYTHON_PATH 指定的解释器必须能够导入完整的工作器堆栈:
arcgis_mcp
pydantic
pydantic_core
arcpy
对于首次安装 Windows 的用户,服务器的 command 和
ARCPY_PYTHON_PATH 应使用同一个 arcgis-mcp-env\python.exe。
开发时仍支持将服务器与工作器放在不同环境中,但工作器解释器必须包含
自己的兼容版 arcgis-mcp-bridge 安装及所有运行时依赖项。
配置 MCP 主机之前,请运行此预检:
$ArcGISMcpPython = "C:\...\envs\arcgis-mcp-env\python.exe"
& $ArcGISMcpPython -c "import sys, arcgis_mcp, pydantic, pydantic_core; print(sys.executable); print('Bridge runtime OK')"
& $ArcGISMcpPython -c "import arcpy; print('ArcPy', arcpy.GetInstallInfo().get('Version'))"
环境变量
| 变量 | 必需 | 用途 |
|---|---|---|
ARCPY_PYTHON_PATH | 是 | 已获得许可的工作器 python.exe 的绝对路径;该解释器必须能够解析 arcgis_mcp、Pydantic/pydantic_core 和 ArcPy |
ARCGIS_MCP_ALLOWED_ROOTS | 否 | 以 Windows ; 分隔的 PathGuard 边界根目录;默认为 ~/Documents/ArcGIS/Projects |
ARCGIS_MCP_SCRATCH_GDB | 否 | 默认输出工作空间;若省略,则默认为 <first allowed root>\scratch.gdb;该 GDB 必须已存在 |
ARCGIS_MCP_LOG_FILE | 否 | 可选的轮转日志文件路径 |
ARCGIS_MCP_LOG_LEVEL | 否 | DEBUG、INFO、WARNING 或 ERROR;默认为 INFO |
ARCGIS_MCP_TOOL_TIMEOUT | 否 | 每个作业的超时时间(秒),必须为正数;默认为 600 |
ARCGIS_MCP_MAX_WORKERS | 否 | ArcPy 并发工作器数量上限;默认为 2,以保护许可证席位和 RAM |
Claude Desktop 配置
每种配置都必须设置 ARCPY_PYTHON_PATH,并将其指向设置命令报告的
已获得许可的解释器。
请将下方所有占位符路径替换为计算机上现有的路径。 临时地理数据库必须已存在。
选项 1:统一的 PyPI 环境 — Windows 推荐
MCP 服务和 ArcPy 工作器使用同一个解释器:
{
"mcpServers": {
"arcgis-mcp-bridge": {
"command": "C:\\...\\envs\\arcgis-mcp-env\\python.exe",
"args": [
"-m",
"arcgis_mcp.server"
],
"env": {
"ARCPY_PYTHON_PATH": "C:\\...\\envs\\arcgis-mcp-env\\python.exe",
"ARCGIS_MCP_ALLOWED_ROOTS": "C:\\GIS\\Data;C:\\Workspace",
"ARCGIS_MCP_SCRATCH_GDB": "C:\\GIS\\Data\\scratch.gdb",
"ARCGIS_MCP_MAX_WORKERS": "2"
}
}
}
}
在此配置中,command 和 ARCPY_PYTHON_PATH 的值应相同。请使用设置命令
返回的 python_exe 值。
选项 2:本地 Git 开发环境
Layer A 使用仓库 .venv,Layer B 使用已配置的
arcgis-mcp-env:
{
"mcpServers": {
"arcgis-mcp-bridge": {
"command": "C:\\path\\to\\arcgis-mcp-bridge\\.venv\\Scripts\\python.exe",
"args": [
"-m",
"arcgis_mcp.server"
],
"env": {
"ARCPY_PYTHON_PATH": "C:\\...\\envs\\arcgis-mcp-env\\python.exe",
"ARCGIS_MCP_ALLOWED_ROOTS": "C:\\GIS\\Data;C:\\Workspace",
"ARCGIS_MCP_SCRATCH_GDB": "C:\\GIS\\Data\\scratch.gdb",
"ARCGIS_MCP_MAX_WORKERS": "2"
}
}
}
}
此拆分环境配置假定工作器已使用上述任一 Path B 设置命令从仓库进行配置。
如果 uv sync --locked 已将项目安装到仓库的 .venv 中,则无需设置
PYTHONPATH。
全局解析到的 arcgis-mcp-server 命令也能正常工作,但这会形成
拆分环境部署。除非工作器环境已单独配置并验证,否则不建议将此方式用于
Windows 首次设置。
重启 MCP 主机后,请先调用 health_check。它会验证服务器到工作器的
IPC 通信路径,并报告所选的工作器解释器,但不会导入 ArcPy。然后运行
只读 ArcGIS 工具或上方的 ArcPy 预检命令,以验证已获得许可的运行时。
06 — 故障排除
Worker process exited with code 1
如果 MCP 服务已启动,但所有 ArcGIS 工具都失败,请检查服务日志中的工作进程回溯。常见的环境相关原因包括:
ModuleNotFoundError: No module named 'arcgis_mcp'
ModuleNotFoundError: No module named 'pydantic_core._pydantic_core'
这些错误通常意味着工作进程使用了不同的 Python 安装、桥接程序未安装到工作进程所用的解释器中,或者工作进程中的 Pydantic 安装不完整或不兼容。建议的修复方法是使用上文所述的统一环境配置。
对于建议的统一配置,请确认两个值完全相同:
"command": "C:\\...\\envs\\arcgis-mcp-env\\python.exe"
"ARCPY_PYTHON_PATH": "C:\\...\\envs\\arcgis-mcp-env\\python.exe"
在该确切解释器中安装或更新桥接程序:
$ArcGISMcpPython = "C:\...\envs\arcgis-mcp-env\python.exe"
& $ArcGISMcpPython -m pip install --upgrade arcgis-mcp-bridge
验证所选的可执行文件和桥接程序依赖项:
& $ArcGISMcpPython -c "import sys, arcgis_mcp, pydantic, pydantic_core; print(sys.executable); print('Bridge runtime OK')"
然后单独验证 ArcPy:
& $ArcGISMcpPython -c "import arcpy; print('ArcPy', arcpy.GetInstallInfo().get('Version'))"
如果桥接程序验证仍然在 pydantic_core 中失败,请在同一环境中重新安装 Pydantic,以便 pip 恢复匹配的编译依赖项:
& $ArcGISMcpPython -m pip install --upgrade --force-reinstall --no-cache-dir "pydantic>=2.5,<3"
更改 Python 环境或配置后,请彻底重启 MCP 主机。
ARCPY_PYTHON_PATH 指向了错误的可执行文件
Windows conda 环境通常会将解释器放在环境根目录中:
C:\...\envs\arcgis-mcp-env\python.exe
请勿使用其他全局 Python 安装,也不要使用不存在的
arcgis-mcp-env\Scripts\python.exe 路径。
临时地理数据库启动错误
默认的临时工作空间为:
<first allowed root>\scratch.gdb
该工作空间必须已存在。请在 ArcGIS Pro 中创建它,或将
ARCGIS_MCP_SCRATCH_GDB 设置为一个现有的文件地理数据库,然后再重启
MCP 主机。
health_check 成功,但 ArcGIS 工具仍然失败
health_check 有意在不导入 ArcPy 的情况下验证服务与工作进程之间的进程边界。成功结果可确认 IPC 和解释器选择正常,但不能证明 ArcPy 或可选的 Esri 扩展许可可以加载。
运行上文中的 ArcPy 预检命令,并检查结构化工作进程错误中的
not_found、license、geoprocessing 或 internal 详情。
首次调用 ArcGIS 工具超时
每次工具调用都会启动一个新的工作进程并导入 ArcPy。这通常需要
10–30 秒,但在实时防病毒软件扫描 ArcGIS Pro 原生 DLL 的机器上,冷启动导入耗时曾达到约 230 秒;DLL 缓存后,后续调用会很快。在这类机器上,请将
ARCGIS_MCP_TOOL_TIMEOUT 保持为默认值 600 秒(或更高)。是否将 ArcGIS Pro 安装目录排除在实时扫描之外,应由该机器的管理员根据安全要求决定。
import_from_geojson 和几何类型
除非另有指定,ArcPy 的 JSONToFeatures 会将 .geojson 文件读取为多边形,并静默丢弃其他几何类型。因此,桥接程序会检测文件中的几何类型并显式传入。如果文件混合了点、线和多边形,则会按类型统计数量并拒绝导入;请为每种类型分别导入一次,并设置 geometry_type。如果导入后得到的要素数为零,程序会明确报错,而不会返回空要素类。
07 — 兼容性
| ArcGIS Pro | 内置 Python | 状态 |
|---|---|---|
| 3.3 | 3.11 | ✅ 参考平台 |
| 3.4 | 3.11 | ⚠ 社区报告可用;请通过预检进行验证 |
| 3.6 | 3.13 | ✅ 社区已验证:完整测试套件和运行时基准测试(#24) |
| 3.7 | 3.13 | ✅ 维护者已验证运行时基准测试(结果) |
| 3.1–3.2 | 3.9 | ❌ 当前软件包要求 Python >=3.11,因此不受支持 |
仅限 Windows。 ArcPy 需要在 Windows 上安装具有许可的 ArcGIS Pro。 Layer A 可在其他平台上用于开发和模拟 CI,但 Layer B 需要 ArcGIS Pro。
桥接程序包本身要求 Python 3.11 或更高版本。克隆的 Python 环境低于 3.11 的 ArcGIS Pro 版本无法运行当前工作进程程序包。
08 — 许可证
Apache License 2.0。请参阅 LICENSE。
评论
一个开放协议,规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话,MCP 服务负责提供工具、资源和提示模板,两者通过标准消息通信,同一个服务可以被不同客户端复用。