mcpField
A
ArcGIS MCP Bridge

ArcGIS MCP Bridge

本地服务
github.com/muend开发工具236 天前更新

关于 ArcGIS MCP Bridge

ArcGIS MCP Bridge 是一个本地优先的 MCP 服务,向 LLM Agent 暴露 100 个 ArcGIS Pro / ArcPy 地理处理工具。它采用双进程架构,并通过 PathGuard 限制文件系统访问、对破坏性操作设置确认门槛,适合 Windows 上持有 ArcGIS Pro 许可的 GIS 用户。

主要功能

  1. 01100 个声明式地理处理工具
  2. 02Layer A 与 Layer B 双进程隔离
  3. 03PathGuard 文件系统沙箱
  4. 04破坏性操作需 confirm 参数确认
  5. 05基于 JSON-RPC 2.0 的 stdio 传输

适用场景

  1. 01通过自然语言执行缓冲区分析、融合和栅格计算
  2. 02在 ArcGIS Pro 中批量检查和修复几何数据
  3. 03将手绘地块草图配准后提交到地理数据库

MCP 相关

该项目是一个 MCP 服务,通过 stdio JSON-RPC 向 Claude Desktop 等 MCP 主机暴露 ArcPy 地理处理工具。

配置

本地服务的配置在各客户端中通用,复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置
{
"mcpServers": {
"arcgis-mcp-bridge": {
"command": "uvx",
"args": [
"arcgis-mcp-bridge"
],
"env": {
"ARCPY_PYTHON_PATH": "<ARCPY_PYTHON_PATH>",
"ARCGIS_MCP_ALLOWED_ROOTS": "<ARCGIS_MCP_ALLOWED_ROOTS>",
"ARCGIS_MCP_SCRATCH_GDB": "<ARCGIS_MCP_SCRATCH_GDB>",
"ARCGIS_MCP_MAX_WORKERS": "<ARCGIS_MCP_MAX_WORKERS>"
}
}
}
}
启动命令uvx arcgis-mcp-bridge
需要配置的环境变量
ARCPY_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+)。各客户端的配置文件位置不同,请参考客户端文档。

安装包
pypiarcgis-mcp-bridge0.6.8

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具,维护者暂未提供工具列表。

详细介绍

PyPI - Version PyPI - Downloads CI Python 3.11+ License Tools Ruff uv arcgis-mcp-bridge MCP server smithery badge

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-bridgegeo2004/MCP-ArcGISPronicogis (C#/.NET)
工具100~15~10
依赖同步确定性(uv.lock)命令式(requirements.txt)原生 NuGet
传输stdio JSON-RPC基于文件的 IPC命名管道
安全架构已记录的 PathGuard 沙箱未指定 / 默认主机访问权限未指定 / 默认主机访问权限
arcpy 隔离双进程架构单进程执行插件进程内执行
CI(离线验证)✅ 支持❌ 不支持❌ 不支持
许可证Apache-2.0MITMIT

亮点:草图 → GIS 工作流

手绘地块边界 → 照片 → 地理数据库要素类。 ORB+RANSAC 图像配准、HSV 墨迹分割、直接提交到 GDB。 无需手动数字化。

**演示即将推出。**预览草图转 GIS 工作流:

  1. 在纸上画一个多边形并拍照。
  2. 向 Claude 提问:“使用 extract_sketch_to_gis 将此照片与我的底图配准, 并将结果提交到我的 GDB。”
  3. 要素类会显示在 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 种工具分类矩阵

#领域工具数主要能力
1map_layer_management10.aprx 地图、图层顺序/可见性/符号系统、相机、保存
2data_management22要素类/地理数据库生命周期、字段、Describe、Excel/GeoJSON/CSV 交换
3geometry_analysis23叠加分析、融合/合并、选择、连接、邻近分析、渔网
4coordinate_reference_projection4基于 WKID 定义/投影矢量数据和栅格数据、CRS 查询
5raster_operations15地图代数、分区统计、DEM 坡度/坡向/山体阴影、水文分析
6vision_analytics1草图转 GIS:ORB+RANSAC 配准 → HSV 墨迹 → 提交到 GDB
7export_layout9PDF/PNG 图件、DPI 控制、地图框、文本/图例、页面尺寸
8editing_topology7修复/检查几何、追加、去重、差异比较、拓扑验证
9network_analysis4服务区、路径规划、起讫点成本矩阵、最近设施
10spatial_statistics5平均中心、标准差椭圆、核密度、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_path fixture 在真实目录上进行测试:沙盒内的有效读取/写入会通过;路径遍历(.. 段)、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.33.11✅ 参考平台
3.43.11⚠ 社区报告可用;请通过预检进行验证
3.63.13✅ 社区已验证:完整测试套件和运行时基准测试(#24)
3.73.13✅ 维护者已验证运行时基准测试(结果)
3.1–3.23.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。

评论

支持 Markdown

第一次接触 MCP?

从协议是什么,到在客户端里装上第一个服务,这几条回答覆盖了大多数入门问题。

一个开放协议,规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话,MCP 服务负责提供工具、资源和提示模板,两者通过标准消息通信,同一个服务可以被不同客户端复用。