qgis-mcp

Servidor MCP que controla QGIS para generar mapas temáticos sobre el shape (polígono) de un proyecto. Las capas aparecen en el lienzo de QGIS a medida que se agregan, y cada mapa queda como diseño de impresión en el Administrador de diseños, listo para retocar. Además se exporta en PDF/PNG y las capas recortadas se guardan en un GeoPackage.

Cliente MCP  ──stdio──▶  servidor qgis-mcp  ──socket 127.0.0.1:9876──▶  complemento QGIS MCP (dentro de QGIS)

El mismo paquete es el servidor y el complemento de QGIS. Si no quieres abrir QGIS, QGIS_MCP_MODE=headless ejecuta todo con PyQGIS sin ventana y guarda un .qgz junto a cada mapa.

Capas que sabe dibujar

El campo para clasificar y el de etiquetas se detectan solos (por ejemplo ZONA_VIDA, CUENCA, ORDEN, USO, NOMBRE); se pueden indicar con field y label_field. El área del proyecto siempre se dibuja encima como contorno rojo.

Cada hoja lleva título, leyenda (solo con lo visible), norte, barra de escala, escala numérica, cuadrícula de coordenadas y una nota con proyecto, sistema de referencia, fuentes y fecha.

Related MCP server: QGIS MCP Server

Herramientas

En QGIS, set_project_area agrega el área como contorno rojo y encuadra el mapa; add_layer coloca cada capa con su estilo en el grupo Capas temáticas según el orden de dibujo; cada mapa generado crea un grupo oculto Mapa: título con las capas recortadas y un diseño con el mismo título (generar de nuevo el mismo título lo reemplaza).

Ejemplo de conversación: "Usa C:/proyecto/area.shp como área del proyecto, agrega zonas de vida, cuencas, ríos y volcanes de C:/datos/, y genera la serie de mapas en A3 con ríos como referencia en cada hoja."

Instalación

Necesitas QGIS 3.28 o superior (probado con 3.34).

1. Complemento de QGIS

Desde una copia de este repositorio, con cualquier Python 3.10+:

pip install -e .
qgis-mcp-install-plugin            # o: python -m qgis_mcp.install_plugin --profile otro_perfil

Esto copia el paquete a la carpeta de complementos del perfil (default):

• Windows: %APPDATA%\QGIS\QGIS3\profiles\default\python\plugins\qgis_mcp

• macOS: ~/Library/Application Support/QGIS/QGIS3/profiles/default/python/plugins/qgis_mcp

• Linux: ~/.local/share/QGIS/QGIS3/profiles/default/python/plugins/qgis_mcp

Reinicia QGIS y activa QGIS MCP en Complementos ▸ Administrar e instalar complementos. El servidor del complemento se inicia solo (botón QGIS MCP en la barra de herramientas para detenerlo; QGIS_MCP_AUTOSTART=0 lo desactiva al abrir).

2. Servidor MCP

El servidor solo necesita Python 3.10+ y el paquete mcp; habla con QGIS por el socket. En Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "qgis": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/Esaban17/qgis-mcp", "qgis-mcp"]
    }
  }
}

Variables opcionales: QGIS_MCP_HOST, QGIS_MCP_PORT (por defecto 9876, también la lee el complemento) y QGIS_MCP_TIMEOUT en segundos (por defecto 600).

Modo sin QGIS abierto

Con "env": {"QGIS_MCP_MODE": "headless"} el servidor usa PyQGIS directamente, así que debe ejecutarse con el Python de QGIS: en Linux un entorno creado con python3 -m venv --system-site-packages sobre python3-qgis; en Windows C:\Program Files\QGIS 3.34.4\bin\python-qgis.bat -m qgis_mcp; en macOS el Python de QGIS.app con QGIS_PREFIX_PATH=/Applications/QGIS.app/Contents/MacOS.

Desarrollo

.venv/bin/pip install -e '.[test]'
.venv/bin/python -m pytest

Las pruebas crean datos sintéticos de las 15 capas alrededor de un proyecto ficticio en Guatemala (tests/sample_data.py) y generan mapas reales con QGIS. tests/test_plugin.py levanta el complemento sobre el proyecto de QGIS y le habla por el socket. Sin PyQGIS, solo se ejecutan las pruebas del catálogo y del servidor.