ArcgisMCP

ArcgisMCP

通过本机 ArcPy 向 AI 客户端提供 ArcGIS 数据读取、地理处理和加工链路查询，支持 Streamable HTTP 与 stdio。

Beta / AI 编写声明：本项目代码由 AI 编写和迭代，可能存在 Bug、兼容性问题及未覆盖的边界情况。测试通过不代表所有场景可靠；请先在测试数据上验证，保留独立备份，重要成果由人工核验。

部署

1. 准备环境与安装

需要 Windows、可用的 ArcGIS Pro / ArcPy 环境及相应工具许可，以及独立的 Python 3.10+（推荐 3.12）。MCP 服务和 ArcPy worker 使用不同解释器；不要向服务虚拟环境安装 ArcPy。

当前主要在 ArcGIS Pro 3.1.5 的环境中实测，其他版本需要验证。ArcGIS Pro 和 Python 安装完成后，在 PowerShell 中执行：

git clone https://github.com/1834495203/ArcgisMCP.git
cd ArcgisMCP
./scripts/install.bat

安装脚本会创建 .venv、安装服务依赖，并登记源码路径；脚本默认使用清华 PyPI 镜像。

2. 告诉服务 ArcPy 在哪里

修改仓库内 config/datasources.json 的 arcpy_python，填写能够导入 ArcPy 的 python.exe 完整路径，不是 arcpy 文件夹。例如默认环境：

{
  "arcpy_python": "C:/Program Files/ArcGIS/Pro/bin/Python/envs/arcgispro-py3/python.exe"
}

上面只展示需要修改的字段，保留配置文件其他设置。使用克隆环境时，填写克隆环境中的 python.exe。

不知道环境位置时，可在 ArcGIS Pro 的 Python 窗口运行下面代码，获取当前环境中的解释器候选路径，再确认文件存在：

import sys
from pathlib import Path
print(Path(sys.prefix) / "python.exe")

也可从 ArcGIS Pro 的包管理器查看当前环境位置。不要直接把 sys.executable 的输出填入配置，它在 Pro 内可能指向 ArcGISPro.exe。

不想修改文件时，可用环境变量覆盖（优先于配置文件，仅对当前 PowerShell 及其启动的进程生效）：

$env:ARCGIS_MCP_ARCPY_PYTHON = "C:/Program Files/ArcGIS/Pro/bin/Python/envs/arcgispro-py3/python.exe"

3. 自检

./scripts/check.bat

自检会启动 ArcPy worker 并检查环境。先解决路径、ArcPy 导入或许可证错误，再接入客户端；首次加载 ArcPy 可能需要几十秒。

客户端接入

以下两种方式任选一种。客户端具体配置文件位置和字段结构以其自身说明为准。

HTTP：先启动服务，再填写地址

在仓库根目录运行，保持该终端运行：

./scripts/run-http.bat

在客户端添加 MCP 服务，选择 Streamable HTTP，URL 填写 http://127.0.0.1:8765/mcp。不是旧版 SSE 端点。

端口被占用时运行 ./scripts/run-http.bat --port 8766，同时修改客户端 URL。需要固定项目时，可追加 --project "D:/projects/demo"；否则连接后让 AI 调用 use_project。

stdio：由客户端启动服务

无需另开 HTTP 服务。在客户端配置以下启动项，把示例中的仓库位置替换为本机实际路径：

{
  "command": "D:/tools/ArcgisMCP/.venv/Scripts/python.exe",
  "args": ["-m", "arcgis_mcp", "--transport", "stdio"],
  "env": {
    "ARCGIS_MCP_PROJECT": "D:/projects/demo"
  }
}

这是单个服务的启动参数示例，按客户端要求放入其 MCP 配置中。ARCGIS_MCP_PROJECT 可省略，然后由 AI 调用 use_project；指定的目录必须存在。command 使用独立服务虚拟环境的 Python，ArcPy Python 仍由前面的配置指定。

确认接入成功

连接后让 AI 调用 arcgis_status 检查环境，再调用 use_project 和 list_datasources 确认项目与数据源。所有数据路径都针对 MCP 服务所在电脑，不是远程客户端的文件系统。

升级代码后重启服务及 worker，客户端重新连接以刷新工具说明。

使用方式

复杂流程可让 AI 用 save_workflow_node 保存 Python 节点，通过 @节点.输出 连接；list_workflows / workflow_nodes 查询，run_saved_workflow 运行，export_workflow 导出脚本。每轮记录代码、说明、输入输出和日志，不必逐个封装 ArcPy 算法。用法与原始数据保护边界见 节点图工作流。默认副本输入；显式 read_only 可直接读取更广泛数据，但强制保护原件需部署执行账户只读权限。

先让 AI 选择服务端存在的项目目录，之后使用相对路径：

use_project(folder="D:/projects/demo")
list_gdb_datasets(gdb="./data/City.gdb")
read_gdb_data(gdb="./data/City.gdb", dataset="roads", limit=5)
buffer(in_features="./data/City.gdb/roads",
       out_features="./results.gdb/roads_buffer", distance="100 Meters")

写操作默认返回 job_id，再查询状态与结果：

job_status(job_id="返回的任务ID")
job_result(job_id="返回的任务ID")

任务成功后，用 result.output 或 result.outputs 中的实际路径继续下一步。queued / running 时继续查询，不要重复提交；failed / unknown 时先检查错误和恢复记录。客户端超时不代表后台任务停止。

可用 job_result(job_id="...", wait_seconds=5) 短暂等待，减少轮询。默认精简字段元数据，detail=true 查看完整原始结果。

需要固定工作库时，可以这样选择（只影响当前会话，不在此处建库）：

use_project(folder="D:/projects/demo", output_gdb="./工作.gdb", auto_create_gdb=False)

工作流使用 configure_workflow_data 配置固定角色库，允许自动建库时在首次使用时创建。若关闭自动建库，应先准备好这些库；默认没有独立 create_gdb 工具。兼容模式中的产出工具支持裸名称写入默认工作库。跨会话配置可写入项目 .arcgis-mcp/datasources.json：

{"output_workspace": "./工作.gdb", "auto_create_gdb": false}

主要功能

默认仅注册 24 个核心工具，GIS 算法通过受审计工作流节点执行。

类别	数量	工具
项目、读取与描述	8	use_project、list_datasources、arcgis_status、describe_data、list_gdb_datasets、read_gdb_data、list_shp_datasets、read_shp_data
历史与任务	5	lineage、explain、job_status、job_result、job_logs
工作流	9	configure_workflow_data、save_workflow_node、workflow_nodes、list_workflows、run_saved_workflow、run_workflow_step、workflow_steps、run_workflow、export_workflow
ArcPy 目录	2	list_arcpy_tools、describe_arcpy_tool

具体参数以客户端获取的工具说明为准。read_gdb_data 支持要素类、表，以及已有属性表的整数分类栅格；不自动建立源栅格属性表。

read_* / describe_data 的字段默认仅返回名称与类型，schema_detail=true 查看完整结构。lineage / explain 默认精简分页，用 next_offset 继续、detail=true 查看完整步骤。

用 list_arcpy_tools 搜索、describe_arcpy_tool 查询参数，然后在节点正文中编写 ArcPy 代码。返回的 execution 是旧兼容适配器状态，不代表该 MCP 执行接口已注册，也不限制节点脚本能使用的算法。

需要旧客户端接口时，在服务全局 config/datasources.json 设置 "tool_profile": "legacy"，或用环境变量 ARCGIS_MCP_TOOL_PROFILE=legacy 覆盖。重启后额外注册 58 个固定 GIS 工具和 run_arcpy_tool、run_unadapted_tool，共 84 个；默认 core。这是启动配置，不随项目或会话切换。旧 allow_arcpy_code 显式开启时还会注册一个拒绝执行代码的兼容入口，不建议启用。

数据保护与链路

• 编辑先复制再操作，保留原件，返回新版本；后续必须使用新路径。
• 显式指定的输出名保持不变；复制编辑自动命名为 原名_工具名（如 D_calculate_fields），重名加 _2、_3。覆盖旧版归档为 原名_overwrite，删除归档为 原名_delete_dataset，同样按序号避让。内部暂存名仍使用随机串；已有历史文件不自动改名。
• 产出写暂存路径，成功后发布。overwrite=true 归档旧目标后替换指定路径，默认拒绝覆盖。
• delete_dataset(confirm=true) 归档原件并移除原路径；delete_features 在副本上删记录。
• 每个 worker 串行执行，同一 GDB 的协作写操作使用工作区锁。ArcGIS Pro 和外部程序仍可能持有冲突锁。
• 同一个 GDB 可保存并连续处理多个要素类，例如 results.gdb/A、results.gdb/A_smooth；保留每步成果不需要每步新建 GDB。delete_dataset 移除原路径但保留归档，delete_features 只在副本删记录，不会移除原要素类。
• lineage(path=...) 回溯来源，lineage(path=..., downstream=true) 查询下游，explain(path=...) 解释步骤和中间成果。

项目运行状态保存在服务端 <项目>/.arcgis-mcp/：

内容	用途
history.sqlite3	持久化任务结果、操作参数和加工链路
transactions/	输出发布和归档的恢复清单
scratch/	干净 CSV 导出等内部临时数据，正常结束后清理

正式成果和保留版本位于对应数据目录或 GDB 中，不是 scratch/。链路针对整个数据集，只记录经本 MCP 执行的操作，不自动记录外部手工修改。

当前适合可信本机使用的 Beta 场景。文件发布与审计提交之间的中断对账尚未完善；复杂关联数据的复制编辑会被拒绝。HTTP 未提供应用层用户鉴权，不应直接暴露公网。完整规则、超时和恢复边界见 数据安全与操作历史。

MCP 负责执行正确、输出可用和数据保护；业务验证由 AI/调用方负责。 不会因融合数量没减少或条件零命中判失败，也不会自动按业务阈值核验面积；需要时由 AI 调用读取、统计工具检查。

开发者如何扩展工具

推荐使用 run_workflow_step 分步推进：先 draft 做分析与实验，再把采用的方案以 final 重算，期间可继续实验。每步保存代码、说明、理由、输入输出及 AI 自定的 step.check 验证；workflow_steps 查询，export_workflow 将成功正式步骤组合成可运行脚本及输入、参数、说明清单。

configure_workflow_data 一次固定原始、过程、临时、交付数据布局。实验数据只进临时区，正式过程与交付分库；步骤不接收任意输出路径，不按步骤创建新 GDB。正式步骤不能依赖实验残留。详见 分步实验、正式流程与导出。

复杂流程现在可直接编写 Python 脚本，通过 run_workflow 提交，或用 python -m arcgis_mcp.workflow 在命令行运行。提交时保存脚本快照和理由；输入先复制，脚本通过步骤 SDK 登记依赖、生成输出或复制编辑，成功中间成果保留。job_logs 查过程，lineage / explain 查逐步链路。原有工具保留兼容，不再要求为每个算法新增 MCP 封装。详见 脚本工作流与示例。

脚本运行器面向可信本机代码，不是安全沙箱；硬编码原始路径或绕过 SDK 的写入无法全面拦截。首版输入快照仍受现有数据保真限制，不支持栅格及复杂关联输入。

仅在 legacy 模式中，可使用 run_arcpy_tool 的已适配调用或 run_unadapted_tool 的有限临时声明。固定算法封装也仅在此模式注册，规则见 兼容临时调用说明。新增流程优先节点脚本。

job_logs(job_id) 查询持久化的理由、实际调用、路径映射、ArcPy 消息和阶段日志；lineage / explain 查询成功的加工链路。这些记录也保存在 history.sqlite3，服务重启后仍可查。

先读 AGENTS.md 和 工具扩展指南。后者提供代码示例、参数约定、注册步骤和测试要求。

工具类型	接入方式
只读查询	继承 Tool，调用 worker 中的只读操作
生成新成果	继承 GeoProcessTool，在 core/ops/ 对应功能域注册操作
修改已有数据	继承 EditTool，在 core/ops/attributes.py 注册复制编辑算法
扩展通用调用	在 core/ops/meta.py 增加经验证的安全分类或专用适配器

固定工具加入 tools/__init__.py 的 ALL_TOOLS 后默认归入兼容组；新增核心接口还需明确加入 CORE_TOOLS，不要无意扩大默认列表。tools/ 负责类型化参数和中文说明，core/ops/ 负责 ArcPy 算法；worker 侧保持 Python 3.9 兼容，不能导入 MCP SDK。

必须复用现有后台任务、复制、暂存发布、工作区锁和持久化审计流程。不要直接修改业务原件、自动删除成功版本、绕过分类执行任意代码，或只加工具名就宣称已安全支持。新增工具要验证实际数据结果及失败行为，并说明未验证范围。

测试

.venv/Scripts/python.exe -X utf8 -m unittest discover -s tests -p test_safety.py
.venv/Scripts/python.exe -X utf8 -m unittest discover -s tests -p test_execution_contracts.py
.venv/Scripts/python.exe -X utf8 -m unittest discover -s tests -p test_unadapted.py
.venv/Scripts/python.exe -X utf8 tests/test_project.py
.venv/Scripts/python.exe -X utf8 tests/test_resolver.py

真实 ArcPy 安全检查：.venv/Scripts/python.exe -X utf8 tests/safety_arcpy_check.py，需要有效 ArcPy 环境，脚本自行启动 worker。

其他端到端脚本的运行要求见各文件说明。需要样例数据时先调整 scripts/make-sample-data.bat 中的 ArcGIS Python 路径，再运行该脚本生成 data/。样例数据和 .arcgis-mcp/ 不随 Git 发布。

许可证

Copyright 2026 1834495203.

本项目采用 Apache License 2.0。ArcGIS Pro、ArcPy 及其他第三方依赖仍遵循各自许可。