Content
# arcpro-mcp
> Control **ArcGIS Pro** with natural language through the **Model Context Protocol (MCP)**.
> Works with Cursor, Claude, and Codex — bring your own LLM, keep your data local.
[](https://github.com/qiobn/arcpro-mcp/actions/workflows/ci.yml)
[](LICENSE)
[](https://www.python.org/)
`arcpro-mcp` lets an AI agent drive a **live ArcGIS Pro session**: inspect projects,
explore layers and attributes, check coordinate systems, and (soon) run geoprocessing
and build layouts — all from a chat prompt in your favorite MCP client.
Unlike Esri's built-in assistant, this is **open source**, connects to **any LLM** via
your MCP client, and acts on your **actual open session** rather than only generating code.
---
## Architecture
ArcGIS Pro hosts `arcpy`, and `arcpy.mp.ArcGISProject("CURRENT")` only works **inside**
the running app. So the MCP server (a separate process started by your client) talks to a
small **bridge** running in ArcGIS Pro's Python window over a local socket:
```
Cursor / Claude / Codex
│ stdio (MCP)
▼
arcpro-mcp (this package, separate process)
│ TCP socket, length-prefixed JSON (127.0.0.1:18748)
▼
arcpro_bridge.py (runs in ArcGIS Pro's Python window)
│ arcpy / arcpy.mp
▼
ArcGIS Pro (live session)
```
Design choices vs. existing tools:
- **Socket, not file polling** — lower latency, cleaner framing for big payloads.
- **Layered + tested** — `src/` package, dependency-free bridge, pytest, CI.
- **Safety first** — read-only by default; destructive tools ask for confirmation;
`execute_python` is **off** unless explicitly enabled; every call is **audit-logged**.
- **Great UX** — structured output, MCP resources, and live **layer-name auto-complete**.
---
## Requirements
- **ArcGIS Pro 3.x** (provides `arcpy`)
- **Python 3.10+** for the MCP server (the `arcgispro-py3` conda env works well)
- An MCP client: **Cursor**, **Claude Desktop**, or **Codex**
- [`uv`](https://docs.astral.sh/uv/) recommended (or plain `pip`)
## Install
```bash
git clone https://github.com/qiobn/arcpro-mcp
cd arcpro-mcp
uv sync # or: pip install -e .
```
## Usage
### 1. Start the bridge in ArcGIS Pro
Open ArcGIS Pro with a project, open the **Python window**, and run:
```python
exec(open(r"C:/path/to/arcpro-mcp/bridge/arcpro_bridge.py").read())
```
You should see `[ArcPro MCP Bridge] Listening on 127.0.0.1:18748`.
### 2. Configure your MCP client
See [`examples/mcp-config.example.json`](examples/mcp-config.example.json). For Cursor or
Claude Desktop:
```json
{
"mcpServers": {
"arcgis-pro": {
"command": "uv",
"args": ["--directory", "C:/path/to/arcpro-mcp", "run", "arcpro-mcp"]
}
}
}
```
### 3. Talk to it
> "Ping ArcGIS Pro and tell me what's in the project."
> "List the layers, then show me the first 10 rows of the roads layer."
> "What's the coordinate system of C:/data/parcels.shp?"
---
## Tools
**Read-only**
| Tool | Description |
| --- | --- |
| `ping` | Connectivity + project status |
| `get_project_info` | Project path, default GDB, maps |
| `list_directory` | List files (confirm paths before loading) |
| `describe_data` | Data type, geometry, extent, **CRS** |
| `list_feature_classes` | Feature classes in a workspace |
| `list_layers` | Layers on the active map |
| `list_fields` | Fields of a dataset/layer |
| `count_features` | Row count of a layer |
| `get_layer_features` | Preview attribute rows |
| `get_unique_values` | Distinct values of a field |
| `get_workspace` / `list_layouts` | Inspect workspace / layouts |
**Write / map-modifying**
| Tool | Description |
| --- | --- |
| `add_vector_layer` / `add_raster_layer` | Add data to a map |
| `remove_layer` | Remove a layer (asks for confirmation) |
| `set_layer_visibility` / `zoom_to_layer` | Toggle / navigate |
| `create_map` / `save_project` | Map and project management |
| `select_by_attribute` / `clear_selection` | SQL-based selection |
| `set_workspace` | Set default GP workspace |
| `run_geoprocessing` | Run **any** ArcPy tool by dotted name |
| `create_layout` / `export_layout` | Build and export print layouts (PDF/PNG/...) |
`execute_python` (arbitrary `arcpy`) exists but is **disabled** unless you set
`ARCPRO_MCP_ALLOW_EXEC=1` in **both** the client env and the ArcGIS Pro env.
## Configuration
| Variable | Default | Description |
| --- | --- | --- |
| `ARCPRO_MCP_HOST` | `127.0.0.1` | Bridge host |
| `ARCPRO_MCP_PORT` | `18748` | Bridge port |
| `ARCPRO_MCP_TRANSPORT` | `stdio` | `stdio` or `streamable-http` |
| `ARCPRO_MCP_ALLOW_EXEC` | _(off)_ | Enable `execute_python` (`1`/`true`) |
| `ARCPRO_MCP_AUDIT_LOG` | `~/.arcpro_mcp/audit.log` | Audit log path (empty to disable) |
| `ARCPRO_MCP_LOG_LEVEL` | `INFO` | Server log level |
## Safety
- Read-only tools are annotated `readOnlyHint` and are always safe.
- Destructive tools (coming next) require confirmation via MCP elicitation.
- `execute_python` is opt-in and double-gated (client + bridge).
- Every requested operation is appended to an audit log for review/replay.
## Roadmap
- [x] v0.1 — socket bridge, read-only tools, audit log, CI, tests
- [ ] v0.2 — write tools (add/remove layer, selection, geoprocessing) with HITL confirm
- [ ] v0.3 — `execute_python` hardening, **reflection middleware** (CRS/units sanity), layouts & export
- [ ] v0.4 — main-thread dispatch queue / optional **.NET Add-In (QueuedTask)** for rock-solid `arcpy.mp`
- [ ] v1.0 — installer, multi-client docs, compound tool mode to cut tokens
## License
MIT — see [LICENSE](LICENSE).
## Acknowledgements
Architecture informed by the excellent
[nkarasiak/qgis-mcp](https://github.com/nkarasiak/qgis-mcp),
[jjsantos01/qgis_mcp](https://github.com/jjsantos01/qgis_mcp),
[geo2004/MCP-ArcGISPro](https://github.com/geo2004/MCP-ArcGISPro), and the safety patterns in
[gdal-mcp](https://github.com/Wayfinder-Foundry/gdal-mcp).
