# ArcGIS Pro MCP — Claude plugin

Drive a **live, open ArcGIS Pro session** from Claude using `arcpy`. Claude can
list layers, describe datasets, run geoprocessing, and inspect the current
project — executing directly against whatever project you have open in Pro.

Because it runs inside your open Pro session, everything happens **locally on
your Windows machine**. This plugin is a distribution wrapper; the actual arcpy
work still requires ArcGIS Pro running in front of you.

---

## Prerequisites (required — this will not work without them)

- **Windows** (ArcGIS Pro is Windows-only)
- **ArcGIS Pro installed** with a **valid license**
- **Claude Code or the Claude desktop / Cowork app** on the same machine
- A one-time `mcp` package install into Pro's Python (handled by `install.ps1`)

If you don't have ArcGIS Pro installed and licensed, this plugin cannot do anything.

---

## What you get

An MCP server (`arcgis-pro`) exposing:

| Tool | Purpose |
|------|---------|
| `project_info()` | Current project path, default gdb, maps |
| `list_layers()` | Layers in the active map (CRS, source) |
| `describe(dataset)` | `arcpy.Describe` on a layer/path + fields |
| `execute_arcpy(code)` | Run arbitrary arcpy in the live session |
| `execute_arcpy_credit(code, reason, confirm_credit)` | Same, for Esri **credit-consuming** ops (gated) |
| `listener_status/pause/resume/stop()` | Control the in-Pro listener |

Plus a bundled skill (`arcgis-pro-workflow`) that teaches Claude the per-session
listener startup, credit-gating etiquette, and releasing Pro's UI when done.

---

## Install

### 1. Install the plugin

**From a local folder (e.g. this OneDrive copy):**
```
/plugin marketplace add "C:\Users\<you>\OneDrive - Econsult Solutions Inc\Documents\Claude\plugins\arcgis-pro-mcp"
/plugin install arcgis-pro-mcp@arcgis-pro-mcp-dev
```

Then **restart** Claude Code / the desktop app so the MCP server loads.

> In the Claude desktop / Cowork app you can also add the marketplace folder
> through the plugin UI instead of the slash command.

### 2. One-time environment setup

The MCP server runs under Pro's Python and needs the `mcp` package there. Run:

```
powershell -ExecutionPolicy Bypass -File .\install.ps1
```

This finds `arcgispro-py3\python.exe`, installs `mcp` into it, and prints the
exact listener line to use each session. If your Pro is on a non-standard path,
update the `command` field in `.claude-plugin/plugin.json` to the path the script
reports.

---

## Using it (every session)

1. Open your project in **ArcGIS Pro**.
2. In Pro's Python window (**View → Python**), paste this **self-locating snippet**.
   It finds `pro_listener.py` wherever Cowork / Claude Desktop installed the plugin —
   you don't need to know the path (it differs per machine and per install):
   ```python
   import glob, os
   _hits = sorted(
       glob.glob(os.path.join(os.environ["APPDATA"], "Claude", "**", "pro_listener.py"), recursive=True),
       key=os.path.getmtime, reverse=True)
   if not _hits:
       raise SystemExit("pro_listener.py not found. Is the arcgis-pro-mcp plugin installed?")
   print("Starting listener from:", _hits[0])
   exec(open(_hits[0]).read())
   ```
   The Python window will show "listener ready" and then appear busy — that's
   expected; the pump is running.
3. Ask Claude to do GIS work ("what layers are in my map?", "describe the parcels
   layer", "reproject X to Y").
4. Claude calls **`listener_stop()`** when finished to free Pro's UI. Re-run the
   snippet next time.

---

## Notes on credits

`execute_arcpy` refuses Esri **credit-consuming** functions (geocoding,
`EnrichLayer`, network solves, `agolservices`, drive-time areas, etc.). Those
must go through `execute_arcpy_credit` with `confirm_credit=True`, which Claude
sets only after you explicitly approve the credit cost.

---

## Troubleshooting

| Symptom | Fix |
|---------|-----|
| "Cannot reach ArcGIS Pro listener at 127.0.0.1:53535" | Pro isn't open, or you haven't run the `exec(...)` listener line this session. |
| MCP server not listed after install | Restart Claude Code / the desktop app. Confirm the `command` path in `plugin.json` points to your real `arcgispro-py3\python.exe`. |
| `ModuleNotFoundError: mcp` | Re-run `install.ps1` (installs `mcp` into Pro's env). |
| Pro UI frozen / unresponsive | Have Claude call `listener_stop()`, or close Pro as a last resort. |
| Port 53535 in use | Another listener is already running, or the port conflicts. Stop the old one, or change `PORT` in both `server.py` and `pro_listener.py`. |

---

## Sharing with your organization

To let coworkers install with one command, put this folder in a **GitHub repo**
and have them run:

```
/plugin marketplace add your-org/arcgis-pro-mcp
/plugin install arcgis-pro-mcp@arcgis-pro-mcp-dev
```

Each coworker still needs the prerequisites above (Pro + license) and must run
`install.ps1` once. You can also pre-wire the marketplace for a team via
`extraKnownMarketplaces` in a shared `.claude/settings.json`.

---

**Author:** Angel Zhong