# postgres-multi-mcp

Servidor MCP que permite a Claude trabajar con **todas las bases de datos de un servidor PostgreSQL** desde una sola configuración. Detecta automáticamente PostGIS y otras extensiones en cada base, sin configuración previa.

Pensado para análisis de datos y trabajo geoespacial: consultas, administración de bases, análisis espacial con PostGIS, ruteo con pgRouting y más, pidiéndolo en lenguaje natural desde Claude Desktop.

---

## Características

- **Multi-base:** una sola entrada en la configuración da acceso a todas las bases del servidor, incluidas las que crees después.
- **Detección automática de extensiones:** si una base tiene PostGIS, el servidor lo reconoce al momento. Si activas PostGIS más adelante, no hace falta reiniciar ni reconfigurar nada.
- **Geometrías legibles:** en lugar del texto hexadecimal ilegible, las geometrías se muestran resumidas (`<geometry: MultiPolygon, SRID 32718, 4.2 KB>`). Los rasters, igual.
- **Dos modos de acceso:** solo lectura (por defecto) o control total.
- **Control total real:** en modo completo funciona todo lo que PostgreSQL permite por SQL, incluido `CREATE DATABASE`, `CREATE EXTENSION`, `VACUUM` y `ALTER SYSTEM`.
- **Resultados acotados:** límite de filas y de tamaño por valor, para que una consulta grande no sature la conversación.
- **Mensajes de error claros**, en español.

## Herramientas

| Herramienta | Qué hace |
|---|---|
| `list_databases` | Lista todas las bases del servidor, con propietario, codificación y tamaño |
| `list_schemas` | Lista los esquemas de una base |
| `list_tables` | Lista tablas, vistas, vistas materializadas y tablas foráneas de un esquema |
| `describe_table` | Columnas, tipos (las geometrías muestran tipo y SRID), restricciones e índices |
| `list_extensions` | Extensiones activas en una base y las disponibles para activar |
| `query_sql` | Consultas de **solo lectura** (`SELECT`, `WITH`, `EXPLAIN`, `SHOW`) |
| `execute_sql` | Cualquier sentencia SQL: escritura, estructura y administración. Solo en modo `full` |

Todas aceptan el parámetro `database`. Si no se indica, se usa la base por defecto.

---

## Requisitos

- **Claude Desktop** (Windows o macOS).
- **PostgreSQL** instalado y funcionando, con un usuario y contraseña para conectarse.
- **PostGIS es opcional.** El servidor funciona sin él y lo detecta solo si lo instalas después.

No necesitas instalar Python: `uv` se encarga de todo.

---

## Instalación

### Paso 1. Instalar `uv` (una sola vez)

`uv` es un instalador de Python que descarga el servidor y sus dependencias automáticamente.

**Windows** — abre PowerShell y ejecuta:

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

**macOS** — abre Terminal y ejecuta:

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

Al terminar, cierra y vuelve a abrir la consola, y comprueba la ruta de `uvx`:

- **Windows:** `where uvx` → normalmente `C:\Users\TU_USUARIO\.local\bin\uvx.exe`
- **macOS:** `which uvx` → normalmente `/Users/TU_USUARIO/.local/bin/uvx`

Anota esa ruta: la usarás en el paso 2.

### Paso 2. Agregar el servidor a Claude Desktop

1. Abre Claude Desktop → **Configuración → Desarrollador → Editar configuración**.
2. **Haz una copia de seguridad** del archivo `claude_desktop_config.json` antes de modificarlo.
3. Dentro de `"mcpServers"`, agrega el bloque `"PostgreSQL"`. Si ya tienes otros servidores, sepáralo con una coma.

**Windows:**

```json
{
  "mcpServers": {
    "PostgreSQL": {
      "command": "C:\\Users\\TU_USUARIO\\.local\\bin\\uvx.exe",
      "args": [
        "--from",
        "https://github.com/bitacorageoespacial/postgres-multi-mcp/archive/refs/heads/main.zip",
        "postgres-multi-mcp"
      ],
      "env": {
        "PG_HOST": "localhost",
        "PG_PORT": "5432",
        "PG_USER": "postgres",
        "PG_PASSWORD": "TU_CONTRASEÑA",
        "PG_DEFAULT_DB": "postgres",
        "PG_ACCESS_MODE": "readonly"
      }
    }
  }
}
```

**macOS:** igual, cambiando `command` por `"/Users/TU_USUARIO/.local/bin/uvx"`.

Reemplaza:

- `TU_USUARIO` por tu usuario del sistema (la ruta que obtuviste en el paso 1).
- `TU_CONTRASEÑA` por la contraseña de tu usuario de PostgreSQL.

> **En el JSON de Windows, las barras de las rutas van dobles** (`\\`). Si tu contraseña contiene comillas `"` o barras invertidas `\`, escríbelas como `\"` y `\\`.

### Paso 3. Reiniciar Claude Desktop

1. Cierra Claude Desktop **por completo**: en Windows, clic derecho en su ícono de la bandeja del sistema (junto al reloj) → **Salir**. Cerrar la ventana no basta.
2. Ábrelo de nuevo.
3. Ve a **Configuración → Desarrollador**: el servidor `PostgreSQL` debe aparecer **En ejecución**.

La primera vez puede tardar unos segundos, mientras `uv` descarga el servidor.

### Paso 4. Probar

En una conversación nueva, pídele a Claude:

> Lista mis bases de datos de PostgreSQL

Si responde con tus bases, todo está funcionando.

---

## Configuración

Todas las opciones se definen en el bloque `"env"` de la configuración de Claude.

| Variable | Por defecto | Descripción |
|---|---|---|
| `PG_HOST` | `localhost` | Servidor de PostgreSQL |
| `PG_PORT` | `5432` | Puerto |
| `PG_USER` | — | Usuario (obligatorio) |
| `PG_PASSWORD` | — | Contraseña |
| `PG_DEFAULT_DB` | `postgres` | Base usada cuando no se indica ninguna |
| `PG_ACCESS_MODE` | `readonly` | `readonly` (solo lectura) o `full` (control total) |
| `PG_MAX_ROWS` | `1000` | Máximo de filas devueltas por consulta |
| `PG_STATEMENT_TIMEOUT_MS` | `60000` | Tiempo máximo por sentencia, en milisegundos |
| `PG_MAX_VALUE_CHARS` | `5000` | Máximo de caracteres por valor de texto; los más largos se recortan |

### Modos de acceso

| Modo | Qué permite |
|---|---|
| `readonly` | Solo consultas. Cualquier intento de modificar algo lo rechaza el propio PostgreSQL. `execute_sql` queda desactivada |
| `full` | Todo lo que tu usuario de PostgreSQL pueda hacer: insertar, borrar, crear y eliminar tablas y bases, activar extensiones, cambiar la configuración del servidor |

> ⚠️ **Sobre el modo `full`:** si te conectas con un superusuario (como `postgres`), Claude podrá hacer **cualquier cosa** en el servidor, incluido borrar bases completas. Claude Desktop te pide aprobar cada llamada: **revisa el SQL antes de aprobarlo**, sobre todo si contiene `DROP`, `DELETE`, `TRUNCATE` o `UPDATE`, y evita la opción "permitir siempre" para `execute_sql`. Mantén respaldos de las bases importantes.
>
> Para limitar lo que Claude puede hacer, conéctate con un usuario de PostgreSQL con menos permisos: el servidor nunca supera los permisos del usuario configurado.

---

## Uso

Algunos ejemplos de lo que puedes pedirle a Claude:

- "¿Qué tablas tiene la base `catastro`?"
- "Describe la tabla `predios` y dime en qué sistema de coordenadas está"
- "Calcula el área en hectáreas de cada predio"
- "¿Qué predios se superponen entre sí?"
- "Crea una base llamada `proyecto_rio` con PostGIS activado"
- "¿Qué extensiones puedo activar en esta base?"

### Geometrías

Las columnas `geometry`, `geography` y `raster` se muestran resumidas para no saturar la conversación:

```
<geometry: MultiPolygon, SRID 32718, 4.2 KB; usa ST_AsText o ST_AsGeoJSON para ver coordenadas>
```

Para ver las coordenadas, la consulta debe usar `ST_AsText(geom)` o `ST_AsGeoJSON(geom)`. Claude lo hace solo cuando lo necesitas.

---

## Limitaciones

| Limitación | Detalle |
|---|---|
| **No hay consultas entre bases** | PostgreSQL no permite unir tablas de dos bases distintas en una misma consulta. Claude consulta cada base por separado. Para cruces frecuentes, usa varios esquemas en una sola base, o la extensión `postgres_fdw` |
| **Sentencias que van solas** | `CREATE DATABASE`, `DROP DATABASE`, `VACUUM` y `ALTER SYSTEM` deben enviarse sin otras sentencias en la misma llamada |
| **Instalar extensiones** | El servidor puede **activar** extensiones (`CREATE EXTENSION`), pero no instalar sus archivos. PostGIS, por ejemplo, se instala con Stack Builder en Windows |
| **Respaldos** | `pg_dump` y `pg_restore` son programas externos: no se ejecutan desde el servidor |
| **Operaciones muy largas** | Las que superen `PG_STATEMENT_TIMEOUT_MS` se cancelan. Para operaciones pesadas, aumenta ese valor |

---

## Configuración opcional del servidor PostgreSQL

Estos ajustes no son del MCP, sino de tu servidor PostgreSQL. Son opcionales, pero recomendables.

### Registro de cambios de estructura

Hace que PostgreSQL anote en su registro cada `CREATE`, `DROP` y `ALTER`, indicando qué aplicación lo hizo. Muy útil para saber, por ejemplo, quién borró una base. Ejecuta como superusuario:

```sql
ALTER SYSTEM SET log_statement = 'ddl';
ALTER SYSTEM SET log_line_prefix = '%m [%p] %a %u@%d ';
SELECT pg_reload_conf();
```

Cada cambio hecho por Claude aparecerá identificado como `postgres-multi-mcp`.

### Exportar rasters con PostGIS (Windows)

Por seguridad, PostGIS viene con todos los formatos raster desactivados. Para exportar a GeoTIFF, PNG y JPEG:

```sql
ALTER SYSTEM SET postgis.gdal_enabled_drivers = 'GTiff PNG JPEG';
ALTER SYSTEM SET postgis.gdal_datapath = 'C:/Program Files/PostgreSQL/18/gdal-data';
SELECT pg_reload_conf();
```

GDAL admite muchos más formatos (COG, JPEG2000, NetCDF, HFA/IMG de ERDAS, etc.), que puedes agregar a la lista si los necesitas. Evita `ENABLE_ALL`.

Si los GeoTIFF exportados salen **sin sistema de coordenadas**, GDAL no encuentra los datos de PROJ. Agrégalos como variables de entorno **solo del servicio de PostgreSQL** (no del sistema, para no afectar a ArcGIS Pro o QGIS). En PowerShell **como administrador**:

```powershell
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Services\postgresql-x64-18" -Name "Environment" -PropertyType MultiString -Value @("PROJ_LIB=C:\Program Files\PostgreSQL\18\share\contrib\postgis-3.6\proj", "GDAL_DATA=C:\Program Files\PostgreSQL\18\gdal-data")
Restart-Service postgresql-x64-18
```

Ajusta las rutas y el nombre del servicio (`Get-Service *postgres*`) a tu versión de PostgreSQL y PostGIS.

---

## Solución de problemas

En Claude Desktop, ve a **Configuración → Desarrollador → PostgreSQL → Ver registros**.

| Problema | Causa probable |
|---|---|
| El servidor aparece como "failed" y el registro dice `ENOENT` | La ruta de `uvx` en `command` está mal escrita, o le faltan las barras dobles `\\` |
| Claude Desktop ignora la configuración | El JSON tiene un error: una coma de más o de menos, o una comilla sin cerrar |
| `password authentication failed` | Usuario o contraseña incorrectos |
| `connection refused` / `could not connect` | El servicio de PostgreSQL no está activo, o el puerto es otro |
| `no existe la base de datos` | El nombre de la base está mal escrito, o `PG_DEFAULT_DB` apunta a una base que no existe |
| `cannot execute ... in a read-only transaction` | Se intentó modificar algo en modo `readonly`, o con `query_sql`. Usa `execute_sql` con `PG_ACCESS_MODE` en `full` |
| `is being accessed by other users` al borrar o copiar una base | Hay conexiones abiertas a esa base (por ejemplo, en pgAdmin). Ciérralas, o usa `DROP DATABASE nombre WITH (FORCE)` |

---

## Actualizar

`uv` guarda una copia del servidor. Para descargar la versión más reciente, ejecuta en la consola:

```
uv cache clean postgres-multi-mcp
```

y reinicia Claude Desktop.

## Desinstalar

Borra el bloque `"PostgreSQL"` de la configuración de Claude Desktop y reinícialo. Si quieres liberar espacio, ejecuta también `uv cache clean postgres-multi-mcp`.

---

## Licencia

[MIT](LICENSE) © 2026 bitacorageoespacial

Este proyecto se ofrece tal cual, sin garantías. Úsalo con responsabilidad, sobre todo en modo `full`.