arcgis-mcp-bridge

Quick Start

arcgis-mcp-bridge requires Windows, a licensed ArcGIS Pro installation, and Python 3.11 or newer for the bridge package.

Install the bootstrap package using one package manager:

# Option A — pip
py -m pip install --upgrade arcgis-mcp-bridge

# Option B — uv
uv pip install --upgrade arcgis-mcp-bridge

Then clone ArcGIS Pro's Python environment:

# The final JSON report contains the target `python_exe` path.
py -m arcgis_mcp.setup_env

If the installed console command is available on PATH, arcgis-mcp-setup is equivalent to py -m arcgis_mcp.setup_env.

Important for Windows systems with multiple Python installations: the setup is not complete until arcgis-mcp-bridge is installed into the reported arcgis-mcp-env\python.exe. Use that same interpreter for both the MCP server command and ARCPY_PYTHON_PATH. This prevents worker failures caused by packages or native extensions being loaded from another Python environment.

See 05 — Installation for the complete setup and configuration.

100 declarative geoprocessing tools. Two isolated processes. One security floor.

A secure, local-first, asynchronous MCP server exposing ArcGIS Pro's ArcPy engine to Claude Desktop and other MCP hosts over stdio JSON-RPC.

Technical write-up: Building a Secure MCP Bridge for ArcGIS Pro and ArcPy

Why arcgis-mcp-bridge?

Highlight: Sketch → GIS Pipeline

Hand-drawn parcel boundary → photo → geodatabase feature class. ORB+RANSAC image registration, HSV ink segmentation, direct GDB commit. No manual digitizing required.

Demo coming soon. To preview the sketch-to-GIS pipeline:

1. Draw a polygon on paper and photograph it.
2. Ask Claude: "Use extract_sketch_to_gis to register this photo against my basemap and commit the result to my GDB."
3. The feature class appears in ArcGIS Pro — no manual digitizing.

00 — Example Prompts

After health_check succeeds, talk to Claude naturally:

"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 — Core Architecture & Philosophy

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]

Layer A — Async Event-Driven Server (arcgis_mcp/server.py). FastMCP on the bridge interpreter. Owns the stdio channel, validates every request against frozen Pydantic v2 contracts, dispatches work via asyncio.create_subprocess_exec — the event loop never blocks on a geoprocessing call and never holds a thread lock. Layer A contains zero module-level arcpy or cv2 imports (verified by grep in the audit gate); it cannot crash on Esri's native code because it never touches it.

Layer B — Subprocess ArcPy Isolation Worker (arcgis_mcp/worker.py). Spawned per job on the licensed ArcGIS Pro interpreter (ARCPY_PYTHON_PATH). The only place import arcpy is legal; cv2 loads lazily inside the one vision tool that needs it. Worker stdout is rebound to stderr at startup — the single sanctioned stdout write is the final NDJSON result frame, so native ArcObjects chatter can never corrupt the JSON-RPC channel. A native crash terminates the worker, not the server: the parent converts a non-zero exit into a structured error frame.

Declarative registry (arcgis_mcp/registry.py). Each tool is one ToolSpec(name, category, description, input_model, worker_fn, destructive). One generic proxy factory materializes all 100 catalog MCP endpoints in Layer A; one generic run_tool dispatcher serves them in Layer B. The catalog is exposed alongside three core endpoints: health_check, list_layers, and execute_spatial_tool. Adding catalog tool #101 touches two files — never the runtime loops.

Every failure crossing the process boundary is classified: validation · security · license · geoprocessing (with the full arcpy.GetMessages() stack) · internal.

02 — The 100-Tool Census Matrix

Esri extension licenses (Spatial, Network) are managed through one shared context manager and checked back in via finally on normal Python exception paths. Worker-process isolation contains native failures to the current job, while unavailable licenses return a structured error frame instead of terminating the MCP server.

Destructive Mutation Safety Floor

Ten state-mutating tools refuse to run without an explicit confirm: true payload token. The gate fires in the dispatcher before the 10–30 s arcpy import is paid, and the registry refuses to even register a destructive spec whose contract lacks a confirm field:

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 carries an additional expression-channel floor: the default expression_type is ARCADE (Esri's sandboxed expression language), and PYTHON3 — which executes code inside the worker — is rejected at the Layer-A contract boundary unless confirm: true is explicitly supplied. raster_calculator expressions are constrained to a pure map-algebra grammar (identifiers, numbers, operators; no quotes, no dunder access) by a contract validator.

03 — Automated Quality Gate & Testing

Licensed-runtime evidence is reported separately in the benchmarks/ method card. Its committed result uses a real ArcGIS Pro worker and a dedicated scratch GDB; it is not pooled with the mocked unit-test count or presented as validation of all 100 geoprocessing tools.

Scope, stated plainly: the automated gate currently consists of 86 unit tests spanning the PathGuard boundary, the Pydantic contracts, the generic registry path-guard and registration invariants, the worker's error-boundary mapping, and Settings environment validation. It exercises the catalog's structural contracts and every security-critical seam — it does not claim multi-scenario validation of the 100 geoprocessing tools themselves, which execute against a licensed ArcGIS runtime that no CI runner has.