QGIS + MCP + OpenCode: cómo conectar QGIS con un agente de IA

Los Sistemas de Información Geográfica (SIG) son herramientas increíblemente potentes, pero también complejas. QGIS es probablemente el SIG de escritorio de software libre más completo y usado del mundo, pero su interfaz tiene una curva de aprendizaje pronunciada. Y aunque sepas usarlo bien, muchas tareas son repetitivas (cargar capas, aplicar estilos, configurar layouts).

¿Y si pudieras decirle a un agente de IA lo que quieres hacer y que lo ejecute directamente sobre QGIS? Sin arrastrar capas, sin buscar el botón correcto, sin recordar dónde está cada opción.

Eso es exactamente lo que permite el MCP de QGIS.

Pero como todo lo que merece la pena, la configuración no siempre sale a la primera. En este artículo te explico qué es MCP, cómo se conecta con QGIS con un agente de IA (OpenCode), la configuración paso a paso, problemas reales que me encontré al hacerlo funcionar, y ejemplos prácticos para sacarle partido.

¿Qué es MCP?

MCP (Model Context Protocol) es un protocolo abierto que permite a modelos de lenguaje (LLMs) interactuar con herramientas y sistemas externos de forma estructurada y segura.

Piénsalo como un USB para la IA: igual que el USB estandarizó la conexión de periféricos al ordenador, MCP estandariza la conexión de la IA con el mundo exterior: bases de datos, APIs, sistemas de archivos y, en este caso, QGIS.

Sin MCP, si le pides a una IA que "cargue un shapefile y lo pinte con un gradiente", lo máximo que puede hacer es generarte el código Python y decirte "copia esto en la consola de QGIS". Con MCP, la IA ejecuta las acciones directamente sobre QGIS.

El flujo es sencillo:

1. Haces una petición en lenguaje natural: "Carga la capa de municipios y coloréalos por población"
2. OpenCode envía la petición al modelo
3. El modelo decide qué herramientas del MCP de QGIS necesita usar
4. Las ejecuta directamente sobre tu QGIS abierto
5. El resultado aparece al instante en tu mapa

Cómo funciona el MCP de QGIS

Arquitectura

Antes de pasar a la configuración, conviene entender cómo se conectan las piezas:

opencode ←→ MCP Server (stdio/HTTP) ←→ TCP :9876 ←→ Plugin QGIS ←→ PyQGIS

El plugin QGIS MCP (github.com/nkarasiak/qgis-mcp) de nkarasiak expone más de 100 herramientas de QGIS a través del protocolo MCP. Pero ojo: el plugin no habla MCP directamente. Tiene un socket TCP interno en el puerto 9876 que solo entiende comandos JSON con un formato propio. Para que opencode (o cualquier cliente MCP) pueda hablar con él, hace falta un MCP Server intermedio que traduzca el protocolo MCP a los comandos que el plugin entiende.

Ese servidor intermedio se ejecuta con uvx y es el que realmente configuraremos en opencode.

Herramientas disponibles

El MCP de QGIS expone las funcionalidades del SIG como herramientas que el agente IA puede invocar. Cada herramienta hace una operación específica:

Hay más de 100 herramientas disponibles. La lista completa cambia con cada versión, pero cubre prácticamente todo lo que harías manualmente en QGIS.

Configuración paso a paso

1. Pre-requisitos

Necesitas tres cosas:

• QGIS instalado (cualquier versión reciente vale, incluida la 4)
• QGIS MCP Plugin instalado en QGIS
• OpenCode instalado
• uv instalado (lo usa uvx para ejecutar el MCP Server sin instalar nada)

2. Instalar el plugin en QGIS

El plugin se llama QGIS MCP. Lo instalas desde el menú de QGIS:

Complementos → Gestionar e instalar complementos... → Buscar "QGIS MCP" → Instalar

Una vez instalado, lo activas desde el menú MCP → Start Server. El plugin se queda escuchando en un socket TCP interno en el puerto 9876.

Puedes comprobar que está vivo:

curl -X POST http://localhost:9876/ -H "Content-Type: application/json" -d '{"action":"ping"}'

3. Configurar OpenCode

Aquí es donde la mayoría de la documentación existente se queda corta. El plugin de QGIS no expone un servidor MCP directamente — solo entiende comandos JSON sobre un socket TCP. Necesitamos un proceso intermedio que haga de traductor.

OpenCode se configura en ~/.config/opencode/opencode.jsonc (o en un opencode.jsonc en la raíz de tu proyecto):

{
  "mcpServers": {
    "qgis": {
      "type": "local",
      "command": [
        "uvx",
        "--from",
        "https://github.com/nkarasiak/qgis-mcp/archive/refs/heads/main.zip",
        "qgis-mcp-server",
      ],
    },
  },
}

Con type: "local", opencode lanza el MCP Server como un subproceso cada vez que arranca. El servidor se comunica con el plugin de QGIS a través del puerto 9876 y expone todas las herramientas a opencode vía MCP.

4. Verificar la conexión

Arranca OpenCode en cualquier directorio:

opencode

Si todo funciona, verás el servidor MCP de QGIS en el panel de herramientas de opencode, listo para aceptar comandos.

Problemas y soluciones

Hasta aquí la teoría. Ahora la práctica, con los problemas reales con los que me topé.

Antes de entrar en cada problema, conviene aclarar: el plugin QGIS MCP está bien documentado. Su README en GitHub incluye la configuración correcta para opencode y para otras herramientas (Claude Code, Codex CLI, Gemini CLI, Cursor, etc.). Los problemas que encontré no fueron por documentación incorrecta, sino por dos cosas:

1. La arquitectura no es evidente hasta que la ves. El plugin tiene dos componentes: un proceso dentro de QGIS (socket TCP) y un servidor MCP externo (uvx). Si no sabes que existe esa separación, es fácil asumir que el plugin expone MCP directamente y configurarlo mal.
2. El README asume que el lector conoce uvx. La compilación de dependencias nativas en la primera ejecución no se menciona, y el timeout de opencode (30s) no es suficiente para ese arranque inicial.

Dicho esto, van los problemas.

Problema 1: Conectar al puerto equivocado

Si ya sabes cómo configurar servidores MCP puede que vayas directamente a opencode y lo hagas con type: "url" apuntando a http://localhost:9876, asumiendo que el plugin de QGIS habla MCP directamente. Pero no: el plugin solo entiende comandos JSON sobre un socket TCP, no el protocolo MCP. Es como intentar hablar HTTP contra un servidor que solo entiende el protocolo de Redis. El plugin viene con un configurador para diferentes agentes, incluido opencode.

Solución:
Usar type: "local" con uvx como se muestra en la configuración de arriba. El qgis-mcp-server es el proceso intermedio que traduce de MCP a los comandos JSON que el plugin entiende. O, alternativamente, tener el servidor HTTP ejecutándose de forma persistente (lo explico al final de esta sección).

Problema 2: Timeout en la primera ejecución

La primera vez que opencode ejecuta uvx --from https://github.com/nkarasiak/qgis-mcp/archive/refs/heads/main.zip qgis-mcp-server, uvx descarga el código y compila dependencias nativas como cryptography. Esta compilación puede superar los 30 segundos, que es el timeout que opencode tiene por defecto para la inicialización de servidores MCP.

Solución:
Ejecutar el comando manualmente una vez antes de arrancar opencode, para que uvx descargue y compile todo y lo deje en caché:

uvx --from https://github.com/nkarasiak/qgis-mcp/archive/refs/heads/main.zip qgis-mcp-server

La primera ejecución puede llevar más de un minuto. Las siguientes serán casi instantáneas.

Si aún así quieres más margen, opencode permite configurar el timeout por servidor MCP:

{
  "mcpServers": {
    "qgis": {
      "type": "local",
      "timeout": 120000,
      "command": [
        "uvx",
        "--from",
        "https://github.com/nkarasiak/qgis-mcp/archive/refs/heads/main.zip",
        "qgis-mcp-server",
      ],
    },
  },
}

Ejemplos prácticos

Cargar y visualizar datos

Pídele que cargue archivos directamente desde tu ordenador y los deje listos para trabajar:

Carga el fichero municipios.gpkg que está en mi escritorio, nómbralo "Municipios" y aplícale un estilo graduado por el campo poblacion usando 5 clases con la rampa de color Viridis.

Añade un fondo OSM con el servicio XYZ.

En segundos tienes la capa en QGIS con el estilo aplicado. Sin ir a buscar el archivo en el navegador de capas, sin acordarte de dónde está el estilo graduado.

Manipular datos

Puedes crear campos nuevos, hacer consultas, filtrar, etc. todo en lenguaje natural:

En la capa Municipios, calcula la densidad de población en un nuevo campo llamado densidad.

¿Cuántos municipios tienen más de 50000 habitantes? Dame los nombres.

El agente consulta los datos, los procesa y te responde con la información. No necesitas saber SQL ni recordar la sintaxis de la calculadora de campos.

Análisis espacial

Las operaciones que antes requerían varios clics en el menú Processing ahora se resuelven con una frase:

Haz una unión espacial entre la capa de municipios y la de estaciones meteorológicas, para que cada municipio tenga el nombre de la estación más cercana.

Calcula la altitud media de cada municipio a partir del raster MDT05 y crea un campo nuevo con esos valores.

Crear mapas y layouts

Le dices cómo quieres el mapa y él lo monta:

Crea un layout llamado "Mapa General", tamaño A4 horizontal. Añade un mapa que ocupe toda la página, una leyenda y una barra de escala. Luego expórtalo como PNG.

Configura un atlas con la capa Municipios. Cada página debe mostrar un municipio. Exporta el atlas como PDF.

Trabajar con el proyecto

También puedes gestionar el proyecto al vuelo:

Guarda el proyecto actual como "analisis.qgz" en el escritorio.

¿Qué capas tengo cargadas ahora mismo en el proyecto?

Limitaciones y consideraciones

No es mágico

El MCP de QGIS es tan potente como el modelo que tengas detrás. Los modelos más capaces (Gemini, Claude, GPT-4) entienden bien el contexto geoespacial y saben qué herramienta llamar en cada caso. Los modelos más pequeños pueden confundir herramientas o necesitar prompts más explícitos. Puedes apoyarte en skills o ficheros de memoria de contexto para ayudarles.

Mapas para imprimir

Usar herramientas de procesado es relativamente sencillo para un LLM, incluso si le pides que cree estilos suele ser bastante eficiente. Pero conseguir que te haga un mapa profesional para imprimir ya es otra cosa.

Pueden trabajar con el layout de mapas, pero conseguir que de primeras hagan un buen diseño no es fácil, aquí es donde está más verde. Necesitarás instrucciones detalladas, un buen modelo e incluso crear skills de diseño si quieres conseguir mapas que puedas considerar como versiones finales.

Necesitas QGIS abierto

El plugin MCP de QGIS actúa como servidor, pero necesita que QGIS esté ejecutándose. Si cierras QGIS, pierdes la conexión. Puedes tener QGIS minimizado, pero tiene que estar abierto.

Operaciones destructivas

Herramientas como remove_layer o delete_features están disponibles, pero el plugin las trata con cuidado. OpenCode también te pide confirmación antes de ejecutar operaciones que modifican datos. Aun así, es recomendable trabajar sobre copias cuando hagas pruebas.

Latencia

Cada llamada al MCP viaja de OpenCode al modelo, del modelo de vuelta, y luego se ejecuta en QGIS. No es instantáneo. Para operaciones simples (cargar una capa, cambiar estilo) es rápido. Para geoprocesos pesados (uniones espaciales, estadísticas zonales), el tiempo depende de la carga de trabajo.

Conclusión

Esto está empezando a eclosionar. Estamos viendo cómo la IA se integra en herramientas que antes requerían años de práctica: programas de retoque fotográfico, diseño 3D, edición de vídeo… herramientas complejas que ahora empiezan a entenderse sin conocerlas a fondo.

Con los SIG pasa algo parecido, pero con un matiz importante: para ciertas tareas como retocar una foto es fácil saber lo que quieres aunque no seas fotógrafo, y aún así te quedarás en la superficie, comparado con alguien con experiencia en la profesión. Analizar datos geográficos, crear mapas o interpretar resultados requiere formación. La IA no sustituye ese conocimiento, pero sí acelera los procesos: ejecuta operaciones, prueba combinaciones, genera mapas base que luego puedes ajustar.

Yo sigo pensando lo mismo que meses atrás, cuando todo esto empezó a explotar. Estamos ante el mayor avance en el mundo de la informática después del ratón. La IA está cambiando por completo la forma en la que interactuamos con el software, y eso de por sí, ya es una maravilla.