ntizar postgres-mcp — PostgreSQL como Servidor MCP
Cuándo usar
- Un agente IA necesita interactuar con PostgreSQL de forma segura y programática
- Necesitas health checks, index tuning y query analysis sin acceso directo a la BD
- Quieres exponer PostgreSQL como herramientas MCP para agentes LLM
- Necesitas modo restricted (solo lectura) para entornos de producción
Cuándo NO usar
- No usas PostgreSQL → este skill es específico de PostgreSQL
- El agente ya tiene acceso directo a la BD → MCP añade capa innecesaria
- Necesitas escritura arbitraria sin validación → el modo restricted lo impide
Instalación
# Docker (recomendado)
docker pull crystaldba/postgres-mcp
# pipx
pipx install postgres-mcp
# uv
uv pip install postgres-mcp
Configuración
# Variable obligatoria
DATABASE_URI=postgresql://user:pass@host:5432/dbname
# Opcional (para LLM optimization experimental)
OPENAI_API_KEY=tu_key
Transportes MCP
- stdio (default) — clientes locales
- SSE — múltiples clientes compartidos
- Streamable HTTP — transporte moderno
9 Herramientas MCP
| Herramienta | Descripción | Modo |
|---|---|---|
list_schemas |
Lista schemas de la BD | Solo lectura |
list_objects |
Lista tablas, vistas, secuencias, extensiones | Solo lectura |
get_object_details |
Columnas, constraints, índices de un objeto | Solo lectura |
execute_sql |
Ejecuta SQL arbitrario | Depende del modo |
explain_query |
EXPLAIN con soporte hypopg y ANALYZE | Solo lectura |
get_top_queries |
Queries más lentos desde pg_stat_statements | Solo lectura |
analyze_workload_indexes |
Recomienda índices óptimos (DTA o LLM) | Solo lectura |
analyze_query_indexes |
Analiza hasta 10 queries y recomienda índices | Solo lectura |
analyze_db_health |
Health checks completos | Solo lectura |
Modos de Acceso
# Desarrollo — lectura/escritura completa
postgres-mcp --access-mode=unrestricted
# Producción — solo lectura con protecciones
postgres-mcp --access-mode=restricted
Seguridad en modo Restricted
- SafeSqlDriver con pglast para validación AST
- Whitelist de ~500+ funciones SQL permitidas
- Whitelist de ~70 extensiones PostgreSQL
- Timeout por defecto 30s
force_readonly=Trueen conexiones- Rechaza COMMIT, ROLLBACK, locking clauses
Extensiones Requeridas (para tuning)
- pg_stat_statements — estadísticas de queries
- hypopg — simulación de índices hipotéticos
Algoritmos de Indexación
1. DTA (Database Tuning Advisor)
Algoritmo greedy basado en el "Anytime Algorithm" de Microsoft SQL Server:
- Identifica queries candidatos para tuning
- Genera candidatos de índices (combinaciones de columnas)
- Búsqueda greedy con análisis Pareto (costo vs beneficio)
- Usa
hypopgpara simular impacto antes de crear índices - Parámetros:
max_index_size_mb,max_runtime_seconds=30,max_index_width=3,pareto_alpha=2.0
2. LLM Optimizer (experimental)
- Usa GPT-4o vía
instructorpara generar sugerencias de índices - Iterativo: LLM sugiere → hypopg evalúa → feedback al LLM
- Requiere
OPENAI_API_KEY - Máximo 5 intentos sin progreso antes de parar
Health Checks (adaptados de PgHero)
| Check | Qué verifica |
|---|---|
| index | Índices inválidos, duplicados, bloated, no usados |
| buffer | Hit rate del buffer cache (tablas e índices) |
| connection | Número y utilización de conexiones |
| vacuum | Salud de VACUUM, riesgo de transaction ID wraparound |
| sequence | Secuencias cerca de exceder su valor máximo |
| replication | Lag entre primary/replicas, status, slots |
| constraint | Constraints inválidos |
Casos de Uso para Mastermind
- Exploración de esquema por agentes
- Diagnóstico de rendimiento automático
- Optimización de índices basada en carga real
- Debugging de queries con EXPLAIN + índices hipotéticos
- Monitoreo proactivo con health checks
Recursos
- GitHub: https://github.com/crystaldba/postgres-mcp
- Licencia: MIT
- Docker:
crystaldba/postgres-mcp