arcmap-mcp

Servidor MCP local para ArcMap 10.5–10.8 (validado en 10.5). 100% abierto, libre y soberano. Permite a un agente IA (Claude Code, Claude Desktop, Gemini CLI, Antigravity, OpenCode…) conducir una sesión viva de ArcMap — listar capas, ejecutar arcpy, encuadrar, simbolizar, exportar series de planos y ver el canvas — igual que hacen los MCP de QGIS y ArcGIS Pro, pero para ArcMap legacy (que ninguno de esos cubre).

Arquitectura (sesión viva, dos piezas)

Cliente IA (Claude Code / Desktop / Gemini / Antigravity / OpenCode)
        │  protocolo MCP (stdio)
        ▼
arcmap_mcp_server.py        ← servidor MCP externo (Python 3 + FastMCP): los schemas
        │                      de las 78 herramientas y el contrato con el cliente
        │  socket TCP local  127.0.0.1:27179
        ▼
Add-in .NET (C#)            ← DENTRO de ArcMap: TcpListener + ArcObjects nativo
  ├─ hilo STA de ArcMap     ← capas, layout, exports, render (con cancelación ESC)
  └─ subprocess Python 2.7  ← arcpy out-of-process sobre un snapshot del .mxd
        │                      (execute_arcpy, Data Driven Pages, análisis ambiental)
        ▼
ArcMap ABIERTO y vivo  →  canvas, capas, layout, exportación

El patrón de dos piezas —servidor MCP externo + puente dentro del GIS hablando un protocolo trivial por socket local— está tomado del MCP de QGIS (open source), el estándar de facto de la categoría. Crédito donde corresponde: este proyecto copia ese diseño y lo lleva a ArcMap.

Las dos piezas son una decisión de diseño, no una provisionalidad:

• El add-in .NET corre dentro de ArcMap y toca el documento vivo vía ArcObjects (COM gestionado por el CLR — estable, sin interop manual). Atiende un comando por conexión en el puerto 27179; lo que muta el mapa se ejecuta en el hilo STA de ArcMap (el único válido para ArcObjects), y lo que es arcpy puro se delega a un proceso Python 2.7 aparte que trabaja sobre una copia temporal del documento — así un análisis largo no congela la interfaz de ArcMap.
• El servidor externo expone las @mcp.tool() por stdio — el transporte que soportan todos los clientes MCP — y reenvía cada comando por TCP local. Servir HTTP desde el propio add-in se evaluó y se descartó: no hay SDK MCP para .NET Framework 4.5, HttpListener exige reservas URL ACL con permisos de administrador (rompería la instalación de un clic) y los clientes stdio necesitarían un proxy igualmente.

Estructura del repo

arcmap-mcp/
├── src/      arcmap_mcp_server.py   ← servidor MCP (regístralo en tu cliente IA)
│             auditor_mxd.py · exportar_mxd.py ← procesos hijo Py2.7 de audit_folder y export_mxd_lote
├── addin/    ArcmapMcp.AddIn/       ← código C# del add-in (+ runner.py embebido)
│             ArcmapMcp.Disco/       ← arcmap-mcp-disco.exe: modo disco de edit_mxd_lote y compare_mxd
│             dist/arcmap-mcp.esriaddin  ← add-in listo para instalar (lleva dentro el .exe)
│             build.ps1              ← build sin Visual Studio (dotnet CLI)
├── docs/     INSTALL.md · TOOLS.md · ROADMAP.md · img/ (capturas)
├── tests/    test_client_protocol.py  ← tests automáticos (no necesitan ArcMap)
│             test_runner_py27.py      ← el runner y el auditor bajo Python 2.7, sin arcpy
│             regresion_sesion_viva.py ← barrido manual del catálogo (ArcMap vivo)
│             regresion_ddp.py         ← barrido del atlas (Data Driven Pages, solo lectura)
│             regresion_disco.py       ← edit_mxd_lote contra copias de un .mxd real (modo disco)
│             sonda_puente.py          ← sonda manual de un comando suelto
├── INSTALAR.bat · ACTUALIZAR.bat · install.ps1 · LEEME.txt ← instalación de un clic
├── start-arcmap-mcp.ps1 · empaquetar.ps1 · requirements.txt · CHANGELOG.md · LICENSE · README.md

| Pieza | Dónde corre | Qué es | |---|---|---| | addin/dist/arcmap-mcp.esriaddin | dentro de ArcMap (.NET/CLR) | El add-in: socket + ArcObjects + subprocess arcpy | | src/arcmap_mcp_server.py | externo (Python 3) | Servidor MCP que registras en tu cliente IA | | start-arcmap-mcp.ps1 | Windows | Lanzador: prepara venv, vigila el túnel, hace ping | | arcmap-mcp-disco.exe | externo, fuera de ArcMap | Modo disco: aplica (edit_mxd_lote) o lee (compare_mxd) un .mxd con los mismos handlers del add-in, sin abrirlo en ArcMap. Viaja dentro del .esriaddin: no hay que instalar nada aparte |

arcmap-mcp se instala en C:\mcp\arcmap-mcp, extraigas el ZIP donde lo extraigas: el instalador copia ahí el paquete y registra esa ruta en tus clientes IA, así que la carpeta donde descomprimiste el ZIP se puede borrar después. Para otra ubicación, INSTALAR.bat -Destino D:\otra\carpeta (fuera de carpetas sincronizadas tipo Drive/Dropbox). Si clonas con git, se usa la carpeta del clon.

Herramientas MCP

78 herramientas sobre ArcMap 10.5 (ver docs/TOOLS.md para el catálogo completo con firmas, ejemplos y los matices de ejecución de cada grupo).

Qué significa «probado», que conviene decirlo con precisión:

• tests/regresion_sesion_viva.py hace 480 comprobaciones contra una sesión de ArcMap real y cubre 56 de las 78 tools, con sus casos de error. 🔴 Modifica el documento abierto (añade capas, cambia simbología, lanza geoprocesos): se lanza contra un mxd de pruebas, nunca contra un proyecto.
• tests/regresion_ddp.py cubre las tres tools del atlas (Data Driven Pages) con 14 comprobaciones, y es de solo lectura sobre el documento: necesita un mxd con atlas habilitado, que en la práctica es siempre uno de producción. Exporta a C:\temp.
• tests/regresion_disco.py prueba edit_mxd_lote contra copias de un .mxd real con 50 comprobaciones, cada una con su control (lo guardado se lee con arcpy en otro proceso; una ruta relativa que se pierde al guardar tiene que salir como no verificada).
• Otros 199 tests corren sin ArcMap (protocolo, argumentos, lectores de .mxd y de Word, runner Python 2.7, instalador).
• export_mxd_lote no pasa por el puente y no está en la regresión: se probó sobre planos reales, con salida idéntica byte a byte a la exportada a mano.
• El resto de tools se ha ejercitado a mano en trabajo real a lo largo de las versiones —series de planos de decenas de páginas, análisis ambiental— pero no están en la regresión automática, así que un fallo suyo no lo caza nadie hasta que aparece.

Esto no es una salvedad de manual. El 2026-09-21, al cubrir geodatabases por primera vez y al lanzar la regresión dos veces en la misma sesión, salió un defecto que llevaba ahí desde versiones anteriores: las workspace factories dejaban de poder instanciarse y con ellas add_layer, describe_data y list_feature_classes, hasta cerrar ArcMap. Está corregido en la 2.12.0 y ya cubierto. Lo que falta por cubrir sigue siendo el sitio donde esperar la próxima sorpresa: si usas una versión anterior a la 2.12.0, ese fallo está latente.

• Sin ArcMap abierto (leen del disco, no pasan por el puente): describe_mxd (versión declarada de un .mxd sin abrirlo, milisegundos) · audit_folder (inventario de TODOS los .mxd de una carpeta: versión, capas, fuentes rotas y definition queries, abriendo cada documento en un proceso aparte con timeout) · get_ole_tables (las tablas de Word incrustadas en un .mxd, leídas del fichero).

• Esenciales: ping · get_arcmap_info · list_layers · zoom_to_layer · export_pdf · refresh · execute_arcpy (código arcpy arbitrario sobre un snapshot del documento — ver matiz en docs/TOOLS.md).

• Series de planos (Data Driven Pages): list_ddp · export_ddp · list_layout_elements · set_text_element · goto_ddp_page · set_definition_query · set_layer_visibility · export_view_png · export_jpg · export_mxd_lote (exporta una lista de .mxd del disco, un proceso por documento: la vía para series).

• Capas y datos: select_by_attribute · clear_selection · get_unique_values · count_features · list_fields · get_layer_info · get_layer_features · add_layer (también servicios WMS, y capas que no entran en la leyenda) · remove_layer · apply_symbology_from_layer · set_scale.

• Tabla de contenidos y leyenda: add_group (capa de grupo vacía) · move_layer (recolocar una capa o grupo sin quitarla) · rename_layer (renombrarla sin sustituirla) · set_legend_item (qué enseña la entrada de leyenda de una capa, sin cambiarle el aspecto; quitarla o moverla) · set_legend (tamaño de letra, columnas y encajar la leyenda en un recuadro sin escalarla).

• Simbología: set_graduated_symbology (rangos, capas de entidades) · set_unique_values_symbology (categorías por valores únicos) · set_raster_symbology (ráster clasificado, estirado o por valores únicos — NDVI, FCC, P95, pendientes, y máscaras categóricas con valores transparentes) · set_single_symbology (un solo símbolo con los colores pedidos) · edit_symbol (cambia solo lo pedido de la simbología que ya tiene la capa) · list_style_symbols / apply_style_symbol (símbolos de tus estilos .style por nombre) · apply_symbology_from_layer (.lyr plantilla).

• Etiquetas: set_labels (expresión, tamaño, color y halo; devuelve cómo quedó cada clase y si el mapa usa Maplex o el motor estándar).

• Marcadores espaciales: get_bookmarks · add_bookmark · remove_bookmark · goto_bookmark.

• Geoprocesamiento y mantenimiento: run_geoprocessing · save_mxd · save_mxd_as · open_mxd · list_broken_data_sources · repair_data_source.

• Visualización y catálogo: get_canvas_screenshot (imagen INLINE, el agente ve el mapa; cancelable con ESC) · describe_data · list_data_frames / set_active_df · set_extent · get_workspace / set_workspace · list_feature_classes / list_tables / list_rasters.

• Análisis ambiental y teledetección (requieren Spatial/3D Analyst; corren fuera del proceso de ArcMap → no congelan la GUI): raster_index (índices espectrales con nombre: NDVI, GNDVI, NDRE, NDWI, MNDWI, NDMI, NBR, SAVI, EVI — con mapeo de bandas Sentinel-2 / Landsat) · hydrology (cuencas, red de drenaje, inundación) · contours · topographic_profile · least_cost_path · calculate_geometry.

La filosofía es híbrida: execute_arcpy es la base universal (cualquier análisis de ArcMap 10.x se puede expresar con él) y los wrappers existen solo para lo repetitivo y de alto valor.

Guía rápida: tu primer plano en 5 pasos

Con el add-in instalado y el servidor registrado en tu cliente IA, esto es el camino corto de "no he tocado nada" a "tengo un PNG". Pídeselo al agente en lenguaje normal; entre paréntesis va la herramienta que acabará usando.

1. Abre ArcMap y pulsa Iniciar en la barra arcmap-mcp. Es el único paso manual, y sin él no hay puente.
2. «¿Está vivo el puente?» (ping). Debe devolver la versión del add-in, el documento abierto y el número de capas. Si dice PUENTE CAIDO, vuelve al paso 1; si dice ocupado, ArcMap está trabajando y te dice en qué y desde cuándo.
3. «Añade esta capa y dime qué hay dentro» (add_layer, list_layers, list_fields). A partir de aquí el agente ya conoce tus datos y sus campos.
4. «Simbolízala y encuádrala» (set_graduated_symbology para rangos, set_unique_values_symbology para categorías, set_raster_symbology si es ráster; luego zoom_to_layer).
5. «Expórtame la vista» (export_view_png, o export_pdf para el layout). Si quieres ver el resultado sin salir del chat, get_canvas_screenshot devuelve la imagen en línea.

Dos atajos que ahorran disgustos desde el primer día. Si vas a trabajar sobre .mxd que no conoces, pasa antes describe_mxd o audit_folder: leen los ficheros sin abrirlos, así que te d