arcpro-mcp

Control ArcGIS Pro with natural language through the Model Context Protocol (MCP). Works with Cursor, Claude, and Codex — bring your own LLM, keep your data local.

arcpro-mcp lets an AI agent drive a live ArcGIS Pro session: inspect projects, explore layers and attributes, check coordinate systems, and (soon) run geoprocessing and build layouts — all from a chat prompt in your favorite MCP client.

Unlike Esri's built-in assistant, this is open source, connects to any LLM via your MCP client, and acts on your actual open session rather than only generating code.

---

Architecture

ArcGIS Pro hosts arcpy, and arcpy.mp.ArcGISProject("CURRENT") only works inside the running app. So the MCP server (a separate process started by your client) talks to a small bridge running in ArcGIS Pro's Python window over a local socket:

Cursor / Claude / Codex
        │  stdio (MCP)
        ▼
arcpro-mcp  (this package, separate process)
        │  TCP socket, length-prefixed JSON  (127.0.0.1:18748)
        ▼
arcpro_bridge.py  (runs in ArcGIS Pro's Python window)
        │  arcpy / arcpy.mp
        ▼
ArcGIS Pro  (live session)

Design choices vs. existing tools:

• Socket, not file polling — lower latency, cleaner framing for big payloads.
• Layered + tested — src/ package, dependency-free bridge, pytest, CI.
• Safety first — read-only by default; destructive tools ask for confirmation; execute_python is off unless explicitly enabled; every call is audit-logged.
• Great UX — structured output, MCP resources, and live layer-name auto-complete.

---

Requirements

• ArcGIS Pro 3.x (provides arcpy)
• Python 3.10+ for the MCP server (the arcgispro-py3 conda env works well)
• An MCP client: Cursor, Claude Desktop, or Codex
• uv recommended (or plain pip)

Install

git clone https://github.com/qiobn/arcpro-mcp
cd arcpro-mcp
uv sync          # or: pip install -e .

Usage

1. Start the bridge in ArcGIS Pro

Open ArcGIS Pro with a project, open the Python window, and run:

exec(open(r"C:/path/to/arcpro-mcp/bridge/arcpro_bridge.py").read())

You should see [ArcPro MCP Bridge] Listening on 127.0.0.1:18748.

2. Configure your MCP client

See examples/mcp-config.example.json. For Cursor or Claude Desktop:

{
  "mcpServers": {
    "arcgis-pro": {
      "command": "uv",
      "args": ["--directory", "C:/path/to/arcpro-mcp", "run", "arcpro-mcp"]
    }
  }
}

3. Talk to it

"Ping ArcGIS Pro and tell me what's in the project." "List the layers, then show me the first 10 rows of the roads layer." "What's the coordinate system of C:/data/parcels.shp?"

---

Tools

Read-only

Tool	Description
ping	Connectivity + project status
get_project_info	Project path, default GDB, maps
list_directory	List files (confirm paths before loading)
describe_data	Data type, geometry, extent, CRS
list_feature_classes	Feature classes in a workspace
list_layers	Layers on the active map
list_fields	Fields of a dataset/layer
count_features	Row count of a layer
get_layer_features	Preview attribute rows
get_unique_values	Distinct values of a field
get_workspace / list_layouts	Inspect workspace / layouts

Write / map-modifying

Tool	Description
add_vector_layer / add_raster_layer	Add data to a map
remove_layer	Remove a layer (asks for confirmation)
set_layer_visibility / zoom_to_layer	Toggle / navigate
create_map / save_project	Map and project management
select_by_attribute / clear_selection	SQL-based selection
set_workspace	Set default GP workspace
run_geoprocessing	Run any ArcPy tool by dotted name
create_layout / export_layout	Build and export print layouts (PDF/PNG/...)

execute_python (arbitrary arcpy) exists but is disabled unless you set ARCPRO_MCP_ALLOW_EXEC=1 in both the client env and the ArcGIS Pro env.

Configuration

Variable	Default	Description
ARCPRO_MCP_HOST	127.0.0.1	Bridge host
ARCPRO_MCP_PORT	18748	Bridge port
ARCPRO_MCP_TRANSPORT	stdio	stdio or streamable-http
ARCPRO_MCP_ALLOW_EXEC	(off)	Enable execute_python (1/true)
ARCPRO_MCP_AUDIT_LOG	~/.arcpro_mcp/audit.log	Audit log path (empty to disable)
ARCPRO_MCP_LOG_LEVEL	INFO	Server log level

Safety

• Read-only tools are annotated readOnlyHint and are always safe.
• Destructive tools (coming next) require confirmation via MCP elicitation.
• execute_python is opt-in and double-gated (client + bridge).
• Every requested operation is appended to an audit log for review/replay.

Roadmap

• [x] v0.1 — socket bridge, read-only tools, audit log, CI, tests
• [ ] v0.2 — write tools (add/remove layer, selection, geoprocessing) with HITL confirm
• [ ] v0.3 — execute_python hardening, reflection middleware (CRS/units sanity), layouts & export
• [ ] v0.4 — main-thread dispatch queue / optional .NET Add-In (QueuedTask) for rock-solid arcpy.mp
• [ ] v1.0 — installer, multi-client docs, compound tool mode to cut tokens

License

MIT — see LICENSE.

Acknowledgements

Architecture informed by the excellent nkarasiak/qgis-mcp, jjsantos01/qgis_mcp, geo2004/MCP-ArcGISPro, and the safety patterns in gdal-mcp.