ArcGIS MCP Bridge

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 · not_found (an input path does not exist; the message names the field and path) · license · geoprocessing (with the full arcpy.GetMessages() stack, or ArcPy's own message for non-geoprocessing calls such as Describe) · internal (exception type and message; the traceback stays in the server log).

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.

In-memory test architecture. tests/conftest.py injects MagicMock proxies into sys.modules["arcpy"] and sys.modules["arcpy.sa"] (with CheckExtension answering "Available") before any package import resolves. The entire suite executes in well under a second, with no ArcGIS installation, no license checkout, and no Esri runtime — locally and in CI identically.

Test scopes.

• tests/test_security.py & tests/test_pathguard.py — the PathGuard boundary firewall, exercised against real directories via pytest's tmp_path fixture: valid reads/writes inside the sandbox pass; traversal (..-segments), UNC, relative, NUL-byte, reserved-device, over-length and out-of-root paths are rejected; write discipline (ArcGIS dataset-name rules, overwrite opt-in) is enforced.
• tests/test_contracts.py — Pydantic contract enforcement: per-tool parameter specs, cross-field validators, frozen / extra="forbid", and the ok-xor-error invariant on the IPC envelope.
• tests/test_registry.py & tests/test_registry_guard.py — registry stream integrity plus generic apply_path_guard enforcement and register invariants — every schema must be a ToolInput subclass, every path_fields entry must reference a valid role, duplicate names are rejected, and every destructive spec must carry its confirm gate.
• tests/test_worker.py — process_frame error-boundary mapping: every failure class (validation, security, license, geoprocessing, internal) maps to its distinct WorkerError.kind.
• tests/test_config.py — Settings.from_environment validation: required variables, directory/file checks, integer bounds, and the fail-fast on a missing scratch geodatabase.

The side-effect import import arcgis_mcp.tools in the registry test is what populates the catalog; it is # noqa-pinned so no linter ever strips it again.

Static analysis. Ruff enforces canonical formatting plus E/W/F/I/B/RUF at 88 columns against a py311 fl