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
GitHub: https://github.com/muend/arcgis-mcp-bridge
PyPI: https://pypi.org/project/arcgis-mcp-bridge/
MCP Registry: io.github.muend/arcgis-mcp-bridge
Esri Community discussion:
https://community.esri.com/t5/python-questions/open-source-mcp-bridge-for-arcgis-pro-arcpy/m-p/1711533#M75310
Feedback wanted
I am especially interested in feedback from GIS developers, ArcPy users, and people building MCP servers.
The main questions are:
- Does this architecture make sense for a local licensed runtime like ArcGIS Pro?
- Which ArcPy tools or workflows should be prioritized next?
- What safety boundaries would be required before using this with real project data?
- Which ArcGIS Pro versions should be tested first?
- Would a warm worker pool be worth the added complexity, or is spawn-per-call isolation the better default?
The project is open source, and feedback is welcome.
Top comments (1)
This is a strong example of why MCP bridges need to be narrow by default. ArcPy is powerful enough that the agent should not get a generic Python doorway; it should get named operations, scoped inputs, and logs that a GIS operator can audit later.