Content
<div align="center">
# QGIS MCP & Claude — Guía General de Instalación 🇵🇪
**Model Context Protocol para QGIS y Claude AI**
[](https://qgis.org)
[](https://python.org)
[](https://claude.ai)
</div>
---
# ¿Qué es QGIS MCP?
**QGIS MCP** conecta Claude AI con QGIS Desktop a través del **Model Context Protocol (MCP)**. Permite que Claude gestione geoprocesos y acciones en QGIS mediante lenguaje natural para:
- Cargar y gestionar capas (vectoriales y raster).
- Ejecutar algoritmos de procesamiento.
- Aplicar simbología.
- Renderizar mapas.
- Ejecutar código PyQGIS.
# ¿Qué vas a lograr?
Al terminar esta guía, podrás **comunicarte con Claude** y que él controle QGIS por ti:
> _"Carga la capa de distritos de Lima y coloréala por departamento"_
> _"Crea un nuevo proyecto y guárdalo en mi escritorio"_
> _"Ejecuta el algoritmo de centroides sobre la capa activa"_
```mermaid
graph TD
A -->[Escribes tu consulta en Claude Desktop] --> |Petición| B(Servidor MCP Python)
B -->|Socket TCP Puerto 9876| C(Plugin QGIS MCP en QGIS)
C -->|Ejecuta acciones| D[PyQGIS]
```
---
# Requisitos previos
| Items | Descarga |
|---|---|
| **Sistema Operativo**: Windows 10/11 | — |
| **Python**: 3.12 o superior (generalmente incluido en QGIS/OSGeo4W) | [Python](https://www.python.org/downloads/release/python-3120/) |
| **QGIS 3.x**: | [QGIS](https://qgis.org/download/) |
| **Claude Desktop**: (la app, no el web) | [Claude](https://claude.ai/download) |
| **Acceso a internet**: para el funcionamiento | — |
---
## Paso 1 — Descarga el plugin (nuestro auto🏎️)
1. Abre tu navegador y ve a:
👉 **https://lefcgis/qgis_mcp_lefcgis**
2. Busca el botón verde que dice **`<> Code`** (está arriba a la derecha de la lista de archivos).
3. Haz clic en él y selecciona **`Download ZIP`**.
*(Busca el botón verde "Code" → "Download ZIP")*
4. Se descargará un archivo llamado `qgis_mcp-main.zip`.
5. **Descomprime** ese ZIP en una carpeta fácil de encontrar, por ejemplo:
```
C:\Users\TuNombre\Documents\qgis_mcp
```
> 💡 Clic derecho sobre el ZIP → "Extraer todo" → elige la carpeta → Extraer.
---
## Paso 2 — Instala el plugin en QGIS
El plugin es la "parte de QGIS" que se conecta con Claude. Solo tienes que copiar una carpeta al lugar correcto.
### 2.1 — Encuentra la carpeta de plugins de QGIS
1. Abre **QGIS**.
2. En el menú superior ve a: **`Configuración`** → **`Perfiles de usuario`** → **`Abrir carpeta del perfil activo`**
Se abrirá una carpeta en el Explorador de Windows.
3. Dentro de esa carpeta, entra a: **`python`** → **`plugins`**
La ruta completa normalmente se ve así:
```
C:\Users\TuNombre\AppData\Roaming\QGIS\QGIS3\profiles\default\python\plugins
```
### 2.2 — Copia el plugin
1. Abre la carpeta donde descomprimiste el ZIP (Paso 1).
2. Entra a la subcarpeta `qgis_mcp-main`.
3. Ahí verás **varias cosas** (archivos .md, .py, carpetas). Busca **únicamente** la carpeta llamada **`qgis_mcp_plugin`**.
4. **Copia esa carpeta** (clic derecho → Copiar).
5. Pégala dentro de la carpeta **`plugins`** de QGIS que abriste antes.
> ⛔ **ERROR MUY COMÚN:** No copies la carpeta `qgis_mcp-main` completa. Entra dentro de ella y copia solo `qgis_mcp_plugin`. Si pegas la carpeta equivocada, QGIS mostrará el error: *"Este complemento está roto — Falta el archivo de metadatos"*.
Así debe verse el resultado final:
```
✅ CORRECTO:
.../plugins/qgis_mcp_plugin/ ← solo esta carpeta adentro
❌ INCORRECTO (error de metadatos):
.../plugins/qgis_mcp-main/ ← no pegues esto
```
### 2.3 — Activa el plugin en QGIS
1. **Cierra y vuelve a abrir QGIS** (esto es importante para que detecte el nuevo plugin).
2. Ve al menú: **`Complementos`** → **`Administrar e instalar complementos...`**
3. En la pestaña **`Todo`**, busca: `QGIS MCP`
4. Marca la casilla ✅ que aparece a la izquierda.
5. Cierra esa ventana.
> ✅ Si ves "QGIS MCP" en el menú **`Complementos`** de QGIS, el plugin está instalado.
---
## Paso 3 — Instala `uv` (nuestro motor🏁)
`uv` es un pequeño programa que necesita Claude para hablarle al plugin. Solo se instala una vez.
1. Abre **PowerShell** en Windows:
- Presiona `Windows + R`, escribe `powershell`, presiona Enter.
2. Copia y pega este comando exactamente como está, y presiona Enter:
```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
3. Espera que termine. Verás texto corriendo en la pantalla — es normal.
4. Cuando termine, **cierra PowerShell**.
> 🐥 Eso es todo. No necesitas entender qué hace `uv`. Solo instálalo.
---
## Paso 4 — Configura Claude Desktop (nuestro colega 🧠)
Esta es la parte donde le dices a Claude "aquí están las herramientas para usar QGIS".
### 4.1 — Abre el archivo de configuración
1. Abre **Claude Desktop**.
2. Ve a: **`Claude`** (menú superior izquierdo) → **`Configuración`** → **`Desarrollador`** → **`Editar configuración`**
Se abrirá un archivo llamado `claude_desktop_config.json` en el Bloc de Notas (u otro editor de texto).
> 💡 Si no encuentras la pestaña "Desarrollador", busca un botón que diga "Edit Config" o ve directamente a esta ruta en el Explorador de Windows:
> ```
> C:\Users\TuNombre\AppData\Roaming\Claude\claude_desktop_config.json
> ```
### 4.2 — Edita el archivo
El archivo puede estar vacío o tener algo de contenido. **Reemplaza todo** con esto:
```json
{
"mcpServers": {
"qgis": {
"command": "uv",
"args": [
"--directory",
"C:\\Users\\TuNombre\\Documents\\qgis_mcp\\qgis_mcp-main\\src\\qgis_mcp",
"run",
"qgis_mcp_server.py"
]
}
}
}
```
> ⚠️ **MUY IMPORTANTE:** Cambia `TuNombre` por tu nombre de usuario real de Windows, y ajusta la ruta para que coincida con donde descomprimiste el ZIP en el Paso 1.
**Ejemplo real** si tu usuario se llama "Juan" y guardaste en Documentos:
```json
"C:\\Users\\Juan\\Documents\\qgis_mcp\\qgis_mcp-main\\src\\qgis_mcp"
```
> 💡 Nota las **dobles barras invertidas** `\\` — es obligatorio escribirlas así en archivos JSON en Windows.
### 4.3 — Guarda y reinicia Claude
1. Guarda el archivo (`Ctrl + S`).
2. **Cierra y vuelve a abrir Claude Desktop** por completo.
---
## Paso 5 — Activa la conexión en QGIS
Cada vez que quieras usar Claude con QGIS, debes iniciar el servidor desde QGIS:
1. Abre **QGIS**.
2. Dirígete a la ventana de contexto en QGIS
<img width="420" height="256" alt="image" src="https://github.com/lefcgis/qgis_mcp_lefcgis/blob/main/assets/imgs/qgis-plugins-menu_lefc.png" />
3. Ve al menú: **`Complementos`** → **`QGIS MCP`** → **`QGIS MCP`**
<img width="420" height="256" alt="image" src="https://github.com/lefcgis/qgis_mcp_lefcgis/blob/main/assets/imgs/qgis-mcp-start-server_lefc.png" />
Se abrirá un pequeño panel.
4. Haz clic en el botón **`Start Server`** (Iniciar servidor).
Verás un mensaje que dice que el servidor está corriendo en el puerto 9876.
> ✅ Mientras ese panel esté abierto con el servidor activo, Claude puede comunicarse con QGIS.
---
## Paso 6 — ¡Prueba que funciona!
1. Ve a **Claude Desktop**.
2. Escribe este mensaje de prueba:
```
Haz un ping a QGIS para verificar la conexión.
```
4. Claude debería responder confirmando que se conectó correctamente.
5. Luego prueba con algo real:
```
Conéctate a QGIS y dime qué versión tengo instalada.
```
6. ¡Listo! ¿Qué puedes pedirle a Claude ahora?
Una vez conectado, puedes hacer cosas como:
- **"Crea un proyecto nuevo y guárdalo en `C:\Mis proyectos\prueba.qgz`"**
- **"Carga la capa shapefile que está en `C:\datos\distritos.shp` y nómbrala Distritos"**
- **"Haz un mapa de coropletas usando el campo POBLACION con 5 clases y la paleta Spectral"**
- **"Exporta el mapa actual como imagen PNG en mi escritorio"**
- **"Ejecuta el algoritmo de buffer de 500 metros sobre la capa activa"**
---
# Herramientas Disponibles con Claude
El protocolo MCP habilita hasta **51 herramientas**. Las principales incluyen:
<!-- TOOLS_TABLE_START -->
| Herramienta | Descripción |
|---|---|
| `ping` | Verificar conexión con QGIS |
| `get_qgis_info` | Versión de QGIS, plugins instalados |
| `create_new_project` | Crear nuevo proyecto .qgz |
| `load_project` | Abrir proyecto existente |
| `get_project_info` | Info del proyecto activo |
| `add_vector_layer` | Cargar capa vectorial |
| `add_raster_layer` | Cargar capa raster |
| `get_layers` | Listar todas las capas |
| `remove_layer` | Eliminar capa por ID |
| `zoom_to_layer` | Zoom a extensión de una capa |
| `get_layer_features` | Extraer features de una capa |
| `execute_processing` | Ejecutar algoritmos de procesamiento |
| `save_project` | Guardar el proyecto |
| `render_map` | Exportar el mapa como imagen PNG |
| `execute_code` | ⚠️ Ejecutar código PyQGIS arbitrario |
<!-- TOOLS_TABLE_END -->
---
# Problemas frecuentes
| Problema | Solución |
|---|---|
| QGIS no encuentra el plugin | Verifica que copiaste la carpeta `qgis_mcp_plugin` completa, no solo su contenido. |
| Error de ruta en el JSON | Usa dobles barras `\\` y asegúrate de que la ruta exista realmente en tu PC. |
| Claude responde pero QGIS no hace nada | ¿Hiciste clic en "Start Server" en QGIS? Ese paso es obligatorio cada vez. |
| El servidor QGIS se cierra solo | Es normal si cierras QGIS. Solo vuelve a abrirlo y activa el servidor. |
| Alcancé el límites de mensajes | Es normal ya que la cuenta Free tiene tokens limitados. Espera el tiempo indicado por Anthopic o actualiza al plan que tú decidas.|
<img width="420" height="256" alt="image" src="https://github.com/lefcgis/qgis_mcp_lefcgis/blob/main/assets/imgs/tokens.png" />
---
# Advertencias de Seguridad
- ⚠️ La herramienta `execute_code` permite ejecutar **cualquier código Python** en tu máquina. Úsalo con extrema precaución.
- ⚠️ No utilices MCP en proyectos con datos confidenciales si esto viola las políticas de uso de IA de tu organización (Ley N° 31814).
- ⚠️ Mantén el servidor MCP activo solo cuando lo necesites. Puedes desactivar el **Auto-start** del plugin si prefieres un inicio manual.
---
# Uso desde Antigravity / API de Claude
<!-- ANTIGRAVITY_START -->
### Uso desde Antigravity / API
El servidor MCP nativo usa stdio. Para usarlo desde la API o Antigravity, se requiere un proxy HTTP/SSE (como `mcp-proxy`). Para el trabajo diario, Claude Desktop es la opción recomendada.
<!-- ANTIGRAVITY_END -->
---
# Buenas Prácticas Digitales
<!-- BEST_PRACTICES_START -->
- **Especificidad:** Cuanto más específico sea el prompt, mejor el resultado.
- **Backups:** Guarda backups de tus proyectos antes de cada trabajo con Claude.
- **Bitácora:** Documenta tus procesos y prompts exitosos en un markdown.
<!-- BEST_PRACTICES_END -->
---
# 📌 Resumen rápido
1. ✅ Descarga el ZIP de GitHub y descomprímelo.
2. ✅ Copia `qgis_mcp_plugin` a la carpeta de plugins de QGIS.
3. ✅ Instala `uv` con el comando de PowerShell.
4. ✅ Edita `claude_desktop_config.json` con la ruta correcta.
5. ✅ Reinicia Claude Desktop.
6. Cada sesión: Abre QGIS → Complementos → QGIS MCP → **Start Server** → abre Claude.
---
## 🔗 Referencias Útiles
- [Repositorio principal de QGIS MCP](https://github.com/nkarasiak/qgis-mcp)
- [Plugin en QGIS.org](https://plugins.qgis.org/plugins/qgis_mcp_plugin/)
- [Documentación MCP de Anthropic](https://docs.anthropic.com/en/docs/agents-and-tools/mcp)
- [QGIS Oficial](https://qgis.org/) | [QGIS Perú](https://qgis.pe/) | [QGIS España](https://www.qgis.es/)
- 🐍 [Lucho Ferrer](https://linkedin.com/in/luchofgis) | <luis.ferrer.c@uni.pe>
---
*Guía creada en marzo 2026, actualizada en mayo 2026 por Lucho Ferrer*
