ArcMap Desktop 10.8 MCP Bridge

一个面向 ArcMap Desktop 10.8（ArcPy / Python 2.7）的本地 MCP 桥接原型。MCP 服务运行于现代 Python，ArcPy 操作始终由 ArcMap 自带的 Python 2.7 子进程执行。

状态

当前版本已实现文件式 JSON 桥接、目录白名单、任务超时和下列只读工具：

• health_check

• search_arcpy_tools

• describe_mxd

• list_mxd_layers

• describe_dataset

• list_fields

• get_feature_count

• query_features

• get_server_capabilities

• export_mxd_to_png

• export_mxd_to_pdf

• copy_mxd_with_layer_visibility

它还提供受控的 run_geoprocessing，目前仅允许 Buffer_analysis、Clip_analysis、CopyFeatures_management、Dissolve_management、Erase_analysis、Intersect_analysis、Merge_management 与 Project_management。export_mxd_to_png 与地理处理工具一样需要 confirm=true，并且仅能写到 scratch 目录。query_features 默认至多返回 100 条，硬性上限为 1,000 条，以免意外占满 MCP 上下文。

Project_management 的 parameters.out_coor_system 可接受 ArcGIS 坐标系字符串、PRJ 路径或 EPSG:3857 这种 EPSG 写法。

copy_mxd_with_layer_visibility 从不修改输入 MXD：它只在 scratch 目录创建副本，再修改副本中匹配名称的图层可见性。

get_server_capabilities 让 MCP 客户端在执行前读取实际启用的 ArcMap 10.8 工具目录、确认门槛、路径白名单与并发限制；不要根据 ArcGIS Pro 的工具名称假设 Desktop 10.8 也可用。

Related MCP server: pc-control-mcp

高级工具模式

高级模式默认关闭。设置 ARCMAP_MCP_ADVANCED_TOOL_ALLOWLIST 为英文分号分隔的 ArcPy 工具名，例如 Union_analysis;SpatialJoin_analysis;Near_analysis，才会显示 run_advanced_geoprocessing。设置为 ALL 可调用任意非破坏性 GP 工具；Delete_*、Truncate*、Compact*、Remove* 等工具始终拒绝。

高级调用必须传入 args、kwargs，并在 input_paths 与 output_paths 中逐项声明其中全部绝对路径。输出路径必须在 scratch 内，且所有高级调用都需要 confirm=true。这使高级模式仍无法越过数据路径边界。

先用 search_arcpy_tools 搜索本机实际安装的工具名，例如 query="spatialjoin"、query="raster" 或 query="network"，再用 run_advanced_geoprocessing 执行其中一个允许的工具。

本机未安装 ArcMap 时可以使用 ARCMAP_MCP_MOCK=1 运行协议验证；真实 ArcPy 操作必须在已授权的 ArcMap Desktop 10.8 Windows 环境中运行。

安装（MCP 主服务）

使用 Python 3.10+：

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e .

配置

复制配置样例并填写 ArcMap 的 Python 路径：

Copy-Item .env.example .env

常见的 ArcMap Desktop 10.8 Python 路径为 C:\Python27\ArcGIS10.8\python.exe，但请以实际安装位置为准。ARCMAP_MCP_ALLOWED_ROOTS 必须包含数据和项目所在目录；工具会拒绝访问白名单外的路径。

启动

$env:ARCMAP_MCP_PYTHON = 'C:\Python27\ArcGIS10.8\python.exe'
$env:ARCMAP_MCP_ALLOWED_ROOTS = 'D:\GIS\Data;D:\GIS\Projects'
arcmap-mcp

MCP 客户端配置示例：

{
  "mcpServers": {
    "arcmap-10-8": {
      "command": "C:\\path\\to\\.venv\\Scripts\\arcmap-mcp.exe",
      "env": {
        "ARCMAP_MCP_PYTHON": "C:\\Python27\\ArcGIS10.8\\python.exe",
        "ARCMAP_MCP_ALLOWED_ROOTS": "D:\\GIS\\Data;D:\\GIS\\Projects",
        "ARCMAP_MCP_SCRATCH": "D:\\GIS\\Scratch"
      }
    }
  }
}

一键诊断

在 PowerShell 中运行：

.\scripts\diagnose.ps1

脚本不会读写 GIS 数据；它只检查项目虚拟环境、ArcMap Python 路径、访问白名单，并调用 health_check 返回 ArcPy 与许可状态。可传入可选的副本数据路径进行只读计数：

.\scripts\diagnose.ps1 -Dataset .\work\changlong-test\points.shp

审计日志

设置 ARCMAP_MCP_LOG_FILE 后，服务记录操作名、成功/失败、耗时与简短错误信息；不记录工具参数或要素内容。日志文件必须位于 ARCMAP_MCP_SCRATCH 内。

并发保护

默认 ARCMAP_MCP_MAX_WORKERS=1，同一 MCP 服务实例会串行执行 ArcPy 任务，以保护 ArcMap 10.8 的 32 位运行时与许可。可设置为 1–4；ARCMAP_MCP_QUEUE_TIMEOUT_SECONDS 控制任务等待空闲 worker 的最长时间。

首次真实环境验收

启动后先调用 health_check。它应返回 arcpy.GetInstallInfo()、Python 版本和许可状态；之后使用 list_mxd_layers 对一个副本 MXD 测试。默认不允许写操作，地理处理工具会要求 confirm=true 且输出目录必须在白名单内。