arcpro-mcp

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 geoprocessingand 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 viayour 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 insidethe running app. So the MCP server (a separate process started by your client) talks to asmall 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 orClaude 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

Write / map-modifying

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

Configuration

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

• 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 excellentnkarasiak/qgis-mcp,jjsantos01/qgis_mcp,geo2004/MCP-ArcGISPro, and the safety patterns ingdal-mcp.