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 floor (code must parse on the oldest supported interpreter — Layer B). Turkish comments are first-class: the dotless ı/İ are registered under allowed-confusables, so prose is configured around, never rewritten. Mypy runs strict = true with the Pydantic plugin across all 31 source files.

make format          # ruff format + import sorting (mutates)
make lint            # ruff check, mutates nothing
make type-check      # mypy --strict over arcgis_mcp/
make security-audit  # live registry inspection: path roles + confirm gates
make verify-all      # lint + type-check + security-audit, one gate
python -m pytest     # 86/86

04 — Security Framework (PathGuard Sandbox)

Every filesystem argument in every contract declares its role — "read", "write", or "read_list" — in the model's path_fields mapping. One shared enforcement function applies those declarations in both processes: Layer A pre-checks before a worker is ever spawned; Layer B re-validates because it never trusts its parent.

Two boundary controls:

• validate_read(raw: str) — fully resolves the path (symlinks, .., relative segments collapsed before any comparison) and requires containment inside a configured allowed_roots directory. Existence is enforced via a deepest-existing-prefix resolution strategy: the targeted path or its filesystem-resolvable geodatabase prefix must exist. This is what makes GDB-internal datasets (…\city.gdb\roads) first-class — the .gdb container is validated on the filesystem, while the logical tail is constrained to plain dataset names only arcpy can resolve.
• validate_write(raw: str, *, overwrite: bool) — same resolution and containment, plus ArcGIS-legal dataset naming and the overwrite discipline: an existing target is never replaced unless the request explicitly sets overwrite: true.

Any escape pattern — traversal sequences, UNC shares, NUL bytes, reserved device names, out-of-root targets — raises PathSecurityError immediately: the request is answered with a structured security frame and no subprocess is ever orchestrated for it.

05 — 📦 Installation

Choose the onboarding path that matches your use case.

Prerequisites

• Windows with a licensed ArcGIS Pro installation
• Python 3.11 or newer for arcgis-mcp-bridge
• An existing writable directory for ARCGIS_MCP_ALLOWED_ROOTS
• An existing file geodatabase for ARCGIS_MCP_SCRATCH_GDB, unless <first allowed root>\scratch.gdb already exists

Path A: Pure PyPI Installation — Recommended for Windows Users

This is the simplest and most reliable setup for Claude Desktop and other MCP hosts on Windows. The recommended configuration uses the same arcgis-mcp-env\python.exe for both Layer A (the MCP server) and Layer B (the ArcPy worker).

Choose one bootstrap installation command:

# 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.

Copy the python_exe value from the JSON report and assign it below:

$ArcGISMcpPython = "C:\...\envs\arcgis-mcp-env\python.exe"

Choose one installation command:

# Standard installation
& $ArcGISMcpPython -m pip install --upgrade arcgis-mcp-bridge

# OR: include the optional OpenCV-based sketch-to-GIS extension
& $ArcGISMcpPython -m pip install --upgrade "arcgis-mcp-bridge[vision]"

Do not run both commands; the second command already installs the standard package together with the vision extra.

Use $ArcGISMcpPython as both the MCP server interpreter and ARCPY_PYTHON_PATH. This prevents arcgis_mcp, Pydantic, pydantic-core, and other native dependencies from being resolved from a different Python installation.

Path B: Git Clone & Deterministic Development — GIS Contributors

This path keeps Layer A in a hermetic development environment while running ArcPy work in a separately cloned, licensed arcgis-mcp-env worker.

# 1. Clone the repository.
git clone https://github.com/muend/arcgis-mcp-bridge.git
cd arcgis-mcp-bridge

# 2. Create the isolated development environment.
#    Do not use --system-site-packages: Layer A must remain independent of arcpy.
uv venv --python "C:\Program Files\ArcGIS\Pro\bin\Python\envs\arcgispro-py3\python.exe"

# 3. Synchronize the committed dependency resolution.
uv sync --locked

Choose one worker-provisioning command:

# Standard worker
uv run python -m arcgis_mcp.setup_env --install-runtime-deps --project-root .

# OR: worker with the optional OpenCV-based sketch-to-GIS extension
uv run python -m arcgis_mcp.setup_env --with-vision --project-root .

--with-vision implies runtime-dependency installation, so the two commands should not be run consecutively.

The setup command is idempotent, accepts --env-name (default: arcgis-mcp-env) and --dry-run, and emits a JSON report. Set ARCGIS_CONDA_EXE if ArcGIS Pro's conda.exe is not available on PATH.

Worker Interpreter Integrity

Layer B is launched as:

ARCPY_PYTHON_PATH -m arcgis_mcp.worker

The interpreter referenced by ARCPY_PYTHON_PATH must be able to import the complete worker stack:

arcgis_mcp
pydantic
pydantic_core
arcpy

For a first-time Windows installation, use the same arcgis-mcp-env\python.exe for the server command and ARCPY_PYTHON_PATH. Separate server and worker environments remain supported for development, but the worker interpreter must contain its own compatible installation of arcgis-mcp-bridge and all runtime dependencies.

Run this preflight check before configuring the MCP host:

$ArcGISMcpPython = "C:\...\envs\arcgis-mcp-env\python.exe"

& $ArcGISMcpPython -c "import sys, arcgis_mcp, pydantic, pydantic_core; print(sys.executable); print('Bridge runtime OK')"
& $ArcGISMcpPython -c "import arcpy; print('ArcPy', arcpy.GetInstallInfo().get('Version'))"

Environment Variables

Claude Desktop Configuration

ARCPY_PYTHON_PATH is required in every configuration and must point to the licensed interpreter reported by the setup command.

Replace every placeholder path below with an existing path on your machine. The scratch geodatabase must already exist.

Option 1: Unified PyPI Environment — Recommended on Windows

Use the same interpreter for the MCP server and ArcPy worker:

{
  "mcpServers": {
    "arcgis-mcp-bridge": {
      "command": "C:\\...\\envs\\arcgis-mcp-env\\python.exe",
      "args": [
        "-m",
        "arcgis_mcp.server"
      ],
      "env": {
        "ARCPY_PYTHON_PATH": "C:\\...\\envs\\arcgis-mcp-env\\python.exe",
        "ARCGIS_MCP_ALLOWED_ROOTS": "C:\\GIS\\Data;C:\\Workspace",
        "ARCGIS_MCP_SCRATCH_GDB": "C:\\GIS\\Data\\scratch.gdb",
        "ARCGIS_MCP_MAX_WORKERS": "2"
      }
    }
  }
}

The command and ARCPY_PYTHON_PATH values should be identical in this configuration. Use the python_exe value returned by the setup command.

Option 2: Local Git Development Environment

Use the repository .venv for Layer A and the provisioned arcgis-mcp-env for Layer B:

{
  "mcpServers": {
    "arcgis-mcp-bridge": {
      "command": "C:\\path\\to\\arcgis-mcp-bridge\\.venv\\Scripts\\python.exe",
      "args": [
        "-m",
        "arcgis_mcp.server"
      ],
      "env": {
        "ARCPY_PYTHON_PATH": "C:\\...\\envs\\arcgis-mcp-env\\python.exe",
        "ARCGIS_MCP_ALLOWED_ROOTS": "C:\\GIS\\Data;C:\\Workspace",
        "ARCGIS_MCP_SCRATCH_GDB": "C:\\GIS\\Data\\scratch.gdb",
        "ARCGIS_MCP_MAX_WORKERS": "2"
      }
    }
  }
}

This split-environment configuration assumes that the worker was provisioned from the repository with one of the Path B setup commands above. PYTHONPATH is not required when uv sync --locked has installed the project into the repository .venv.

A globally resolved arcgis-mcp-server command can work, but it creates a split-environment deployment. It is not recommended for first-time Windows setup unless the worker environment has been provisioned and verified separately.

After restarting the MCP host, call health_check first. It verifies the server-to-worker IPC path and reports the selected worker interpreter without importing ArcPy. Then run a read-only ArcGIS tool or the ArcPy preflight command above to validate the licensed runtime.

06 — Troubleshooting

Worker process exited with code 1

If the MCP server starts but every ArcGIS tool fails, inspect the server log for the worker traceback. Common environment-related causes include:

ModuleNotFoundError: No module named 'arcgis_mcp'
ModuleNotFoundError: No module named 'pydantic_core._pydantic_core'

These errors usually mean that the worker is using a different Python installation, the bridge was not installed into the worker interpreter, or the worker contains an incomplete or incompatible Pydantic installation. The recommended fix is the unified-environment configuration documented above.

For the recommended unified configuration, confirm that both values are identical:

"command": "C:\\...\\envs\\arcgis-mcp-env\\python.exe"

"ARCPY_PYTHON_PATH": "C:\\...\\envs\\arcgis-mcp-env\\python.exe"

Install or update the bridge inside that exact interpreter:

$ArcGISMcpPython = "C:\...\envs\arcgis-mcp-env\python.exe"
& $ArcGISMcpPython -m pip install --upgrade arcgis-mcp-bridge

Verify the selected executable and bridge dependencies:

& $ArcGISMcpPython -c "import sys, arcgis_mcp, pydantic, pydantic_core; print(sys.executable); print('Bridge runtime OK')"

Then verify ArcPy separately:

& $ArcGISMcpPython -c "import arcpy; print('ArcPy', arcpy.GetInstallInfo().get('Version'))"

If the bridge verification still fails specifically inside pydantic_core, reinstall Pydantic in the same environment so pip restores the matching compiled dependency:

& $ArcGISMcpPython -m pip install --upgrade --force-reinstall --no-cache-dir "pydantic>=2.5,<3"

Restart the MCP host completely after changing its Python environment or configuration.

ARCPY_PYTHON_PATH points to the wrong executable

A Windows conda environment normally places its interpreter at the environment root:

C:\...\envs\arcgis-mcp-env\python.exe

Do not use another global Python installation or a nonexistent arcgis-mcp-env\Scripts\python.exe path.

Scratch geodatabase startup error

The default scratch workspace is:

<first allowed root>\scratch.gdb

It must already exist. Create it in ArcGIS Pro or set ARCGIS_MCP_SCRATCH_GDB to an existing file geodatabase before restarting the MCP host.

health_check succeeds but ArcGIS tools still fail

health_check intentionally verifies the server-to-worker process boundary without importing ArcPy. A successful result confirms IPC and interpreter selection, but it does not prove that ArcPy or an optional Esri extension license can be loaded.

Run the ArcPy preflight command above and inspect the structured worker error for not_found, license, geoprocessing, or internal details.

The first ArcGIS tool call times out

Every tool call starts a fresh worker that imports ArcPy. That usually takes 10–30 s, but a cold import has been measured at ~230 s on a machine where real-time antivirus scans ArcGIS Pro's native DLLs; later calls are fast once the DLLs are cached. Keep ARCGIS_MCP_TOOL_TIMEOUT at its 600 s default (or higher) on such machines. Whether to exclude the ArcGIS Pro installation from real-time scanning is a security decision for the machine's administrator.

import_from_geojson and geometry types

ArcPy's JSONToFeatures reads a .geojson file as polygons unless told otherwise and silently drops other geometries. The bridge therefore detects the geometry type from the file and passes it explicitly. A file that mixes points, lines, and polygons is rejected with a count per type; import it once per type with geometry_type set. An import that yields zero features fails loudly instead of returning an empty feature class.

07 — Compatibility

Windows only. ArcPy requires a licensed ArcGIS Pro installation on Windows. Layer A can run on other platforms for development and mocked CI, but Layer B requires ArcGIS Pro.

The bridge package itself requires Python 3.11 or newer. ArcGIS Pro releases whose cloned Python environment is older than 3.11 cannot run the current worker package.

08 — License

Apache License 2.0. See LICENSE.