Skip to content
Back to search

ArcGIS_Pro_MCP

This is the MCP Server of CartoGI Lab for ArcGIS Pro

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/cartolab-cut--arcgis-pro-mcp/badge.svg)](/listings/cartolab-cut--arcgis-pro-mcp)

HTML

<a href="/listings/cartolab-cut--arcgis-pro-mcp"><img src="/api/listings/cartolab-cut--arcgis-pro-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Requirements

- **ArcGIS Pro** installed (ArcGIS Pro 3.0 or higher; tested on 3.7 with ArcInfo license). - **Python MCP SDK & Pydantic**: Installed in your active ArcGIS Pro Python environment:

  & "C:\Program Files\ArcGIS\Pro\bin\Python\envs\arcgispro-py3\python.exe" -m pip install --user mcp pydantic

2. Verify Installation with the Test Suite

Run the integration test suite to verify tool registration and live ArcPy execution:

$env:PYTHONIOENCODING="utf-8"
& "C:\Program Files\ArcGIS\Pro\bin\Python\envs\arcgispro-py3\python.exe" test_server.py

Expected output:

Ran 6 tests in 32.7s
OK
[PASS] Server initialized with 39 tools, 3 resources, and 3 prompts.
[PASS] Detected ArcGIS Pro version: 3.7, License: ArcInfo
[PASS] Created File GDB at ...
[PASS] Configured SimpleRenderer with hex color #FF5733 and size 14.
[PASS] Configured UniqueValueRenderer classified on field 'PointName'.
[PASS] Configured GraduatedColorsRenderer with 3 natural breaks on field 'Value'.
[PASS] Configured dynamic Arcade labels with expression '$feature.PointName'.
[PASS] Exported styled layer to Exported_SamplePoints.lyrx
[PASS] Applied symbology definition from .lyrx to target point layer.
[PASS] Pydantic v2 schemas and Clean Architecture service layer verified.
[PASS] Successfully imported MCP_Sync.pyt with tools: ['ApplyLyrxToActiveMap', 'SyncAllFromMCP', 'SyncBasemapAndCRS']
[PASS] Executed SyncBasemapAndCRS from MCP_Sync.pyt on test project.

3. Launching the MCP Server

You can launch the server using any of the following methods:

Method A: Direct Command Line

$env:PYTHONIOENCODING="utf-8"
& "C:\Program Files\ArcGIS\Pro\bin\Python\envs\arcgispro-py3\python.exe" run_server.py

Method B: Windows Batch Launcher

run_server.bat

Method C: SSE / HTTP Network Transport

run_server.bat --transport sse --host 127.0.0.1 --port 8000

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 266 lines
  1. # ArcGIS Pro Model Context Protocol (MCP) Server
  2. [![Model Context Protocol](https://img.shields.io/badge/MCP-2.0+-blue.svg)](https://modelcontextprotocol.io)
  3. [![ArcGIS Pro](https://img.shields.io/badge/ArcGIS%20Pro-3.7+-green.svg)](https://www.esri.com/en-us/arcgis/products/arcgis-pro/overview)
  4. [![Python](https://img.shields.io/badge/Python-3.11%20%7C%203.12%20%7C%203.13-blue.svg)](https://www.python.org/)
  5. [![Pydantic](https://img.shields.io/badge/Pydantic-v2.0+-e92063.svg)](https://docs.pydantic.dev/)
  6. An enterprise-grade **Model Context Protocol (MCP)** server that connects AI assistants (such as Claude Desktop, Antigravity, Cursor, and VS Code) directly to **ArcGIS Pro** and **ArcPy**.
  7. It empowers LLMs to inspect `.aprx` projects, run geoprocessing analysis, configure map symbology & labeling, create and manage file geodatabases, query features via SQL, process elevation rasters (hillshade, slope, aspect, contours), and execute complex multi-step ArcPy automation scripts safely.
  8. ---
  9. ## 🌟 Key Features
  10. - **Clean Architecture & Service Layer**: Complete separation of concerns between protocol adapters (`arcgis_pro_mcp/tools/`) and pure geospatial execution (`arcgis_pro_mcp/services/`), fully typed with **Pydantic v2** models and Enums.
  11. - **Cartography & Symbology (`arcpy.mp`)**: Style layers using `SimpleRenderer` (custom colors, sizes, outlines), `UniqueValueRenderer` (categorical fields, color ramps), and `GraduatedColorsRenderer` (Jenks Natural Breaks, Quantile, Equal Interval), plus Arcade dynamic labeling and `.lyrx` export.
  12. - **Zero-Restart Live Sync (`MCP_Sync.pyt`)**: Overcomes ArcGIS Pro `.aprx` file locking. Modify basemaps and coordinate systems via MCP, then apply changes instantly to the active map view in open desktop sessions using the included Python Toolbox.
  13. - **Project & Map Automation**: Inspect `.aprx` projects, list map layers, view field schemas, add spatial data to maps, and export maps or layouts to high-res PNG, JPEG, PDF, or TIFF.
  14. - **Geoprocessing & Spatial Analysis**: High-speed dedicated tools for Buffer, Clip, Intersect, Spatial Join, and Dissolve, plus a universal dynamic tool runner (`run_geoprocessing_tool`) for any ArcPy geoprocessing tool.
  15. - **Geodatabase & Data Management**: Create File Geodatabases (`.gdb`), create point/line/polygon feature classes with custom spatial references (WKID/EPSG), inspect schemas, add fields, and convert between Shapefile, GDB, GeoJSON, and CSV.
  16. - **Attribute Queries & Selections**: Query records with SQL `WHERE` clauses via fast `SearchCursor`, return structured records with optional Well-Known Text (WKT) geometries, select by location/attributes, and calculate summary statistics.
  17. - **Raster & Surface Analysis (`arcpy.sa` / `arcpy.ddd`)**: Extract rasters by mask, generate hillshade, calculate slope/aspect, and generate elevation contour lines from DEMs.
  18. - **Dynamic ArcPy Execution (`execute_arcpy_code`)**: Run multi-step custom Python/ArcPy scripts on the fly with captured `stdout`, `stderr`, and ESRI diagnostic messages.
  19. - **Contextual Resources & Prompts**: Built-in prompts (`gis_spatial_analyst`, `geoprocessing_debugger`, `cartography_specialist`) and live resources (`arcgis://system/info`, `arcgis://system/toolboxes`, `arcgis://system/environments`).
  20. ---
  21. ## 📁 Repository Structure
  22. ```
  23. ArcGIS_Pro_MCP/
  24. ├── arcgis_pro_mcp/
  25. │ ├── __init__.py # Package init
  26. │ ├── server.py # MCP Server instance and registration
  27. │ ├── config.py # Environment auto-detection
  28. │ ├── resources.py # Contextual MCP resources (info, toolboxes, envs)
  29. │ ├── prompts.py # Pre-built GIS workflow assistance prompts
  30. │ ├── utils.py # Error handlers, spatial ref formatters, path sanitization
  31. │ ├── models/ # Pydantic v2 Models & Enums
  32. │ │ ├── __init__.py # Exported schemas and enums
  33. │ │ ├── enums.py # GeometryType, BasemapName, RendererType, etc.
  34. │ │ └── schemas.py # Request validation models
  35. │ ├── services/ # Clean Architecture Service Layer
  36. │ │ ├── __init__.py # Service exports
  37. │ │ ├── system_service.py # Environment & license service
  38. │ │ ├── project_service.py # Project, map, basemap, and CRS service
  39. │ │ ├── cartography_service.py # Symbology, renderers, labeling service
  40. │ │ ├── gp_service.py # Geoprocessing analysis service
  41. │ │ ├── data_service.py # Geodatabase & feature class service
  42. │ │ ├── analysis_service.py # Cursors, SQL queries, and statistics service
  43. │ │ ├── raster_service.py # Terrain, DEM, and surface service
  44. │ │ └── scripting_service.py # Dynamic ArcPy script execution service
  45. │ └── tools/ # MCP Protocol Tool Adapters
  46. │ ├── __init__.py # Consolidated tool exports (39 tools)
  47. │ ├── system.py # Info, licenses, workspaces, extensions
  48. │ ├── projects.py # .aprx inspect, basemaps, CRS, export map
  49. │ ├── cartography.py # Symbology, renderers, labels, lyrx export
  50. │ ├── geoprocessing.py # Buffer, clip, intersect, spatial join, dissolve
  51. │ ├── data_management.py # GDB creation, feature classes, export, schema
  52. │ ├── analysis.py # Queries, select by attribute/location, statistics
  53. │ ├── raster.py # Raster algebra, hillshade, slope, aspect, contours
  54. │ └── scripting.py # Dynamic ArcPy code runner
  55. ├── toolbox/ # ArcGIS Pro Python Toolbox
  56. │ ├── MCP_Sync.pyt # Live sync toolbox (CURRENT session zero-restart)
  57. │ └── README_TOOLBOX.md # Python Toolbox installation and usage guide
  58. ├── run_server.py # Direct Python runner script
  59. ├── run_server.bat # Windows batch launcher (auto-detects Pro Python)
  60. ├── run_server.ps1 # PowerShell launcher
  61. ├── test_server.py # Comprehensive end-to-end integration test suite
  62. ├── claude_desktop_config.json # Ready-to-use configuration for Claude Desktop
  63. ├── pyproject.toml # Python packaging metadata
  64. └── README.md # Documentation
  65. ```
  66. ---
  67. ## 🚀 Quick Start
  68. ### 1. Requirements
  69. - **ArcGIS Pro** installed (ArcGIS Pro 3.0 or higher; tested on 3.7 with ArcInfo license).
  70. - **Python MCP SDK & Pydantic**: Installed in your active ArcGIS Pro Python environment:
  71. ```powershell
  72. & "C:\Program Files\ArcGIS\Pro\bin\Python\envs\arcgispro-py3\python.exe" -m pip install --user mcp pydantic
  73. ```
  74. ### 2. Verify Installation with the Test Suite
  75. Run the integration test suite to verify tool registration and live ArcPy execution:
  76. ```powershell
  77. $env:PYTHONIOENCODING="utf-8"
  78. & "C:\Program Files\ArcGIS\Pro\bin\Python\envs\arcgispro-py3\python.exe" test_server.py
  79. ```
  80. Expected output:
  81. ```
  82. Ran 6 tests in 32.7s
  83. OK
  84. [PASS] Server initialized with 39 tools, 3 resources, and 3 prompts.
  85. [PASS] Detected ArcGIS Pro version: 3.7, License: ArcInfo
  86. [PASS] Created File GDB at ...
  87. [PASS] Configured SimpleRenderer with hex color #FF5733 and size 14.
  88. [PASS] Configured UniqueValueRenderer classified on field 'PointName'.
  89. [PASS] Configured GraduatedColorsRenderer with 3 natural breaks on field 'Value'.
  90. [PASS] Configured dynamic Arcade labels with expression '$feature.PointName'.
  91. [PASS] Exported styled layer to Exported_SamplePoints.lyrx
  92. [PASS] Applied symbology definition from .lyrx to target point layer.
  93. [PASS] Pydantic v2 schemas and Clean Architecture service layer verified.
  94. [PASS] Successfully imported MCP_Sync.pyt with tools: ['ApplyLyrxToActiveMap', 'SyncAllFromMCP', 'SyncBasemapAndCRS']
  95. [PASS] Executed SyncBasemapAndCRS from MCP_Sync.pyt on test project.
  96. ```
  97. ### 3. Launching the MCP Server
  98. You can launch the server using any of the following methods:
  99. #### Method A: Direct Command Line
  100. ```powershell
  101. $env:PYTHONIOENCODING="utf-8"
  102. & "C:\Program Files\ArcGIS\Pro\bin\Python\envs\arcgispro-py3\python.exe" run_server.py
  103. ```
  104. #### Method B: Windows Batch Launcher
  105. ```cmd
  106. run_server.bat
  107. ```
  108. #### Method C: SSE / HTTP Network Transport
  109. ```cmd
  110. run_server.bat --transport sse --host 127.0.0.1 --port 8000
  111. ```
  112. ---
  113. ## ⚙️ Client Configuration
  114. ### Claude Desktop
  115. Add the following to your Claude Desktop configuration file (`%APPDATA%\Claude\claude_desktop_config.json`):
  116. ```json
  117. {
  118. "mcpServers": {
  119. "arcgis-pro": {
  120. "command": "C:\\Program Files\\ArcGIS\\Pro\\bin\\Python\\envs\\arcgispro-py3\\python.exe",
  121. "args": [
  122. "c:\\Pavlos_project's\\ArcGIS_Pro_MCP\\run_server.py"
  123. ],
  124. "env": {
  125. "PYTHONIOENCODING": "utf-8"
  126. }
  127. }
  128. }
  129. }
  130. ```
  131. ### Antigravity / Cursor / VS Code MCP
  132. Add to your MCP settings or configuration file:
  133. ```json
  134. {
  135. "mcpServers": {
  136. "arcgis-pro": {
  137. "command": "cmd.exe",
  138. "args": [
  139. "/c",
  140. "c:\\Pavlos_project's\\ArcGIS_Pro_MCP\\run_server.bat"
  141. ]
  142. }
  143. }
  144. }
  145. ```
  146. ---
  147. ## 🛠️ Complete Tool Catalog (39 Tools)
  148. ### 1. System & Environment
  149. | Tool | Description |
  150. |---|---|
  151. | `get_arcgis_system_info` | Returns version, build number, license level (Basic/Standard/Advanced), and active extension statuses. |
  152. | `set_arcgis_environment` | Configures `arcpy.env` workspace, scratch workspace, overwriteOutput, and output coordinate system. |
  153. | `manage_extension` | Checks availability, checks out, or checks in licenses for Spatial, 3D, Network, and other extensions. |
  154. ### 2. ArcGIS Pro Projects (`.aprx`), Maps & Basemaps
  155. | Tool | Description |
  156. |---|---|
  157. | `inspect_project` | Catalogs all maps, layouts, default geodatabase, and default toolbox inside an `.aprx` project file. |
  158. | `list_map_layers` | Lists all layers and tables in a map, visibility, data sources, and definition queries. |
  159. | `get_layer_properties` | Returns layer geometry type, feature count, bounding extent, coordinate system, and complete field schema. |
  160. | `export_map` | Exports a map layout frame to high-resolution PNG, JPEG, PDF, or TIFF. |
  161. | `add_layer_to_map` | Adds a spatial dataset (Feature Class, Shapefile, Raster) directly into a project map. |
  162. | `set_basemap` | Changes map basemap to Esri gallery basemaps or custom XYZ tile services (Google, OSM, CartoDB). |
  163. | `set_map_spatial_reference` | Updates the spatial reference / coordinate system (EPSG/WKID) of a project map. |
  164. ### 3. Cartography, Symbology & Labeling
  165. | Tool | Description |
  166. |---|---|
  167. | `set_layer_symbology` | Configures layer renderer (`SimpleRenderer`, `UniqueValueRenderer`, `GraduatedColorsRenderer`) with custom colors, sizes, outlines, and break counts. |
  168. | `set_layer_labels` | Toggles dynamic layer labeling with custom Arcade expressions, font sizes, families, and colors. |
  169. | `apply_symbology_from_layer` | Copies symbology and rendering rules from a `.lyrx` layer file or reference layer. |
  170. | `create_layer_file` | Exports a styled layer from an ArcGIS Pro project to a standalone `.lyrx` file. |
  171. ### 4. Geoprocessing & Spatial Analysis
  172. | Tool | Description |
  173. |---|---|
  174. | `run_geoprocessing_tool` | Universal runner: dynamically executes **any** ArcPy geoprocessing tool with keyword arguments and captured logs. |
  175. | `buffer_analysis` | Buffers point, line, or polygon features by distance (meters, kilometers, feet) with dissolve options. |
  176. | `clip_analysis` | Clips spatial features using the boundary of another polygon layer. |
  177. | `intersect_analysis` | Computes geometric intersection across multiple feature classes. |
  178. | `spatial_join` | Joins attributes between datasets based on spatial relationships (intersect, within distance, closest, etc.). |
  179. | `dissolve_features` | Aggregates features based on common attribute values and computes summary statistics. |
  180. ### 5. Geodatabase & Data Management
  181. | Tool | Description |
  182. |---|---|
  183. | `create_file_gdb` | Creates a new File Geodatabase (`.gdb`) at a specified directory. |
  184. | `create_feature_class` | Creates an empty feature class (Point, Polyline, Polygon) with a specified WKID/EPSG coordinate system. |
  185. | `list_gdb_contents` | Catalogs all feature classes, feature datasets, tables, and rasters inside a geodatabase. |
  186. | `describe_dataset` | Returns detailed schema metadata, shape type, extent, spatial reference, and fields for any dataset. |
  187. | `export_dataset` | Exports/converts datasets between Shapefile, GDB Feature Class, GeoJSON, and CSV. |
  188. | `add_field` | Adds a new column/field (Text, Long, Float, Double, Date) to a table or feature class. |
  189. | `delete_dataset` | Safely removes a feature class, table, or raster dataset. |
  190. ### 6. Queries, Selections & Analytical Statistics
  191. | Tool | Description |
  192. |---|---|
  193. | `query_features` | Queries records using SQL `WHERE` clauses with pagination (`limit`/`offset`) and optional Well-Known Text (`WKT`) geometries. |
  194. | `calculate_field` | Computes attribute values using Python 3 expressions or custom function blocks. |
  195. | `select_features_by_attribute` | Filters features with an SQL clause and exports the selection to a new feature class. |
  196. | `select_features_by_location` | Performs spatial selections (contains, within, touches, within distance) and saves the result. |
  197. | `get_summary_statistics` | Calculates statistical aggregates (SUM, MEAN, MIN, MAX, STD) grouped by case fields. |
  198. ### 7. Raster & Surface Analysis
  199. | Tool | Description |
  200. |---|---|
  201. | `describe_raster` | Retrieves band count, cell dimensions, pixel type, extent, and statistical distributions for a raster. |
  202. | `create_hillshade` | Generates a 3D shaded relief hillshade raster from an elevation DEM. |
  203. | `calculate_slope` | Calculates terrain slope in degrees or percent rise from an elevation raster. |
  204. | `calculate_aspect` | Computes terrain aspect (downhill slope facing direction) from a DEM. |
  205. | `create_contours` | Generates contour line vector features from an elevation raster. |
  206. | `extract_raster_by_mask` | Clips/extracts raster pixels matching a polygon or raster mask. |
  207. ### 8. Custom ArcPy Scripting Execution
  208. | Tool | Description |
  209. |---|---|
  210. | `execute_arcpy_code` | Executes an arbitrary block of Python/ArcPy code in a sandboxed context, returning `stdout`, `stderr`, diagnostic messages, and requested output variable values. |
  211. ---
  212. ## 🔄 Live Synchronization with Open ArcGIS Pro (`MCP_Sync.pyt`)
  213. When working with an open ArcGIS Pro session, `.aprx` files are locked by the Pro process.
  214. The MCP Server emits:
  215. 1. `active_basemap_state.json`
  216. 2. `Active_Basemap.lyrx` (or custom `.lyrx` files)
  217. Using **`toolbox/MCP_Sync.pyt`**, you can update your map live from within ArcGIS Pro with zero application restarts:
  218. 1. In ArcGIS Pro **Catalog Pane** -> right-click **Toolboxes** -> **Add Toolbox** -> select `toolbox/MCP_Sync.pyt`.
  219. 2. Run **Sync Basemap and Coordinate System** or **Sync All MCP Changes**.
  220. 3. (Optional) Right-click the tool and click **Add to Quick Access Toolbar** for single-click instant sync!
  221. See [`toolbox/README_TOOLBOX.md`](toolbox/README_TOOLBOX.md) for full details.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.