Building a Secure MCP Bridge for ArcGIS Pro and ArcPy

Muhammed Enes Duran — Wed, 01 Jul 2026 15:44:07 +0000

ArcGIS Pro has a powerful Python runtime through ArcPy, but it is not a lightweight dependency. It is native, licensed, Windows-bound, and tightly coupled to the ArcGIS Pro environment.

That makes it awkward to connect directly to AI tooling.

I built arcgis-mcp-bridge as an independent open-source experiment to solve this problem through the Model Context Protocol (MCP).

GitHub: https://github.com/muend/arcgis-mcp-bridge

PyPI: https://pypi.org/project/arcgis-mcp-bridge/

MCP Registry: io.github.muend/arcgis-mcp-bridge

The problem

ArcPy is extremely useful for GIS automation:

geoprocessing
feature class and geodatabase operations
raster workflows
map and layer management
coordinate reference operations
spatial statistics
network analysis
export and layout workflows

But ArcPy is not a normal pure-Python library. It depends on the licensed ArcGIS Pro Python environment and native Esri runtime components.

For AI/MCP workflows, importing ArcPy directly into the host process is not a clean architecture. If the native runtime crashes, blocks, logs to stdout, or touches the wrong local path, the AI host process is affected too.

So the main design goal was:

Keep the AI/MCP host process lightweight, controlled, and separate from the licensed ArcPy execution runtime.

What arcgis-mcp-bridge does

arcgis-mcp-bridge is a local-first MCP server that exposes ArcGIS Pro’s ArcPy engine over stdio JSON-RPC.

It allows MCP-compatible clients to call a controlled set of ArcPy/geoprocessing tools without importing ArcPy directly into the MCP server process.

The project currently includes:

100 declarative geoprocessing tools
10 GIS verticals
a two-process architecture
ArcPy worker-process isolation
PathGuard filesystem boundaries
confirmation gates for destructive operations
mocked ArcPy tests for CI without an ArcGIS license
optional Sketch-to-GIS / OpenCV pipeline

It is not an official Esri project and not an official Anthropic project. It is an independent open-source bridge for ArcGIS Pro, ArcPy automation, and MCP-based GIS workflows.

Architecture

The project is split into two layers.

Layer A: MCP server

Layer A is the MCP protocol host.

It handles:

stdio JSON-RPC transport
MCP tool registration
Pydantic validation
path validation before worker execution
dispatching jobs to the worker process
returning structured MCP tool results

Layer A does not import ArcPy.

That is intentional. The MCP server should remain lightweight and should not depend on ArcGIS Pro’s native runtime being importable in the same process.

Layer B: ArcPy worker

Layer B is a separate Python process running inside the licensed ArcGIS Pro Python environment.

It handles:

importing ArcPy
executing geoprocessing tools
collecting ArcPy messages
returning one structured JSON result frame

This separation matters because ArcPy can be slow to import, can depend on license state, and can interact with native runtime components. Keeping it in a worker process protects the MCP server process from crashes and native runtime instability.

Why two processes?

The two-process model gives the project a clean failure boundary.

If the ArcPy worker fails, times out, or crashes, the MCP server can return a structured error instead of dying with it.

The basic flow is:

MCP client
   ↓ stdio JSON-RPC
Layer A: MCP server
   ↓ NDJSON subprocess bridge
Layer B: ArcPy worker
   ↓
ArcGIS Pro / ArcPy runtime

This is slower than keeping ArcPy warm in the same process, but it is much safer as a first production boundary.

A future version could add a warm worker pool behind the same execution interface, but the isolation model should remain explicit.

Filesystem safety: PathGuard

GIS workflows often touch sensitive local data:

file geodatabases
enterprise connection files
infrastructure datasets
cadastral data
client project folders
personal or proprietary spatial datasets

Because of that, the bridge uses a PathGuard boundary.

Each filesystem-touching tool declares whether a path is used for:

read
write
read list

The server validates paths before spawning a worker, and the worker validates again before execution.

The goal is not to make arbitrary AI file access convenient. The goal is to make the allowed local execution boundary narrow, explicit, and auditable.

Destructive operation gates

Some ArcPy operations mutate data.

Examples include append, delete, repair geometry, calculate field, projection definition, and other state-changing workflows.

For those operations, the project requires explicit confirmation in the tool input.

The rule is simple:

Destructive tools must require confirm=true.

This gives both the MCP host and the user a clear point where mutation is intentional.

Testing without ArcGIS Pro in CI

A major practical issue with ArcPy projects is CI.

Hosted CI runners usually do not have ArcGIS Pro installed, and they do not have a licensed ArcPy runtime available.

To keep the project testable, the automated test suite mocks ArcPy and focuses on the parts that can be verified without Esri runtime access:

Pydantic contracts
PathGuard behavior
registry invariants
destructive operation gates
worker error mapping
configuration validation
import boundaries

The current suite contains 81 unit tests and runs without ArcGIS Pro.

Real geoprocessing execution still requires a licensed ArcGIS Pro environment on Windows.

Current tool surface

The project currently exposes 100 tools across 10 GIS verticals:

map and layer management
data management
geometry analysis
coordinate reference and projection
raster operations
vision analytics
export and layout
editing and topology
network analysis
spatial statistics

The optional vision component includes a Sketch-to-GIS pipeline using OpenCV. The idea is to extract hand-drawn boundaries from an image and commit them into a geodatabase workflow.

Installation

The package is available on PyPI:

pip install arcgis-mcp-bridge

The project also includes a setup command for preparing an ArcGIS Pro worker environment:

arcgis-mcp-setup

For vision-related functionality:

pip install "arcgis-mcp-bridge[vision]"

Real ArcPy execution requires a licensed ArcGIS Pro Python environment. The server uses ARCPY_PYTHON_PATH to locate the worker interpreter.

Example MCP use cases

Potential workflows include:

list feature classes inside a file geodatabase
buffer parcels and write outputs to a scratch geodatabase
dissolve features by attribute
run raster slope/aspect analysis
export layouts
inspect geometry errors
run spatial statistics tools
prepare repeatable GIS automation tasks from natural language requests

The point is not to let an AI agent freely mutate GIS projects. The point is to expose a controlled, typed, auditable tool surface around common ArcPy workflows.

Links