Postgres MCP — Casos de uso, Instalar & Demo en vivo

Por qué usarlo

Características clave

Solo lectura por diseño — INSERT/UPDATE/DELETE/DDL están bloqueados a nivel de protocolo
Introspección completa del esquema: tablas, columnas, tipos, índices, claves externas
Devuelve planes de consulta (EXPLAIN) para análisis de rendimiento
Cadena de conexión postgres:// estándar — funciona con cualquier BD compatible con PG (Postgres, Neon, Supabase, RDS, Aiven, etc.)

Demo en vivo

Cómo se ve en la práctica

postgres.replay ▶ listo

0/0

Instalar

Elige tu cliente

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://..."
      ]
    }
  }
}

Abre Claude Desktop → Settings → Developer → Edit Config. Reinicia después de guardar.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://..."
      ]
    }
  }
}

Cursor usa el mismo esquema mcpServers que Claude Desktop. La configuración del proyecto prevalece sobre la global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://..."
      ]
    }
  }
}

Haz clic en el icono MCP Servers de la barra lateral de Cline y luego en "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://..."
      ]
    }
  }
}

Mismo formato que Claude Desktop. Reinicia Windsurf para aplicar.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "postgres",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://..."
      ]
    }
  ]
}

Continue usa un array de objetos de servidor en lugar de un mapa.

~/.config/zed/settings.json

{
  "context_servers": {
    "postgres": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-postgres",
          "postgresql://..."
        ]
      }
    }
  }
}

Añádelo a context_servers. Zed recarga en caliente al guardar.

claude mcp add postgres -- npx -y @modelcontextprotocol/server-postgres postgresql://...

Un solo comando. Verifica con claude mcp list. Quita con claude mcp remove.

Casos de uso

Usos del mundo real: Postgres

Responder preguntas de negocio ad hoc sin escribir SQL

👤 PMs, fundadores, cualquiera que prefiera no escribir SQL ⏱ ~10 min beginner

Cuándo usarlo: Tienes una pregunta sobre tus datos ('¿cuántos usuarios regresaron esta semana?') y el dashboard de BI no la tiene.

Requisitos previos

Cadena de conexión postgres:// de solo lectura a una réplica — La mayoría de servicios gestionados de PG (RDS, Neon, Supabase) te permiten crear credenciales de solo lectura
Acceso de red desde donde se ejecuta Claude a la BD — VPN o lista blanca de IP de tu máquina

Flujo

Pide a Claude que introspeccione primero las tablas relevantes

Lista todas las tablas de nuestra BD. Para tablas relacionadas con usuarios, pedidos o sesiones, describe sus esquemas.✓ Copiado

→ Vista general del esquema antes de cualquier consulta
Haz la pregunta real

¿Cuántos usuarios se registraron en los últimos 30 días pero aún no han realizado un pedido? Agrupa por semana de registro.✓ Copiado

→ Claude escribe SQL, lo ejecuta y devuelve una tabla de resultados
Investiga los matices

¿Hay alguna razón por la que este número podría ser engañoso? ¿Eliminaciones suaves? ¿Zona horaria en created_at? ¿Tipos de usuario específicos que deberíamos excluir?✓ Copiado

→ Reconocimiento honesto de peculiaridades de datos

Resultado: Una respuesta defendible a una pregunta de negocio con el SQL, el resultado y los matices — en 2 minutos en lugar de esperar 2 días al equipo de datos.

Errores comunes

Claude escribe una consulta que escanea tu tabla más grande sin límites — Establece statement_timeout = '30s' en la conexión y añade 'siempre incluye LIMIT 1000 por defecto' en tu prompt del sistema
Contar 'usuarios' depende de qué cuenta como usuario (¿eliminado? ¿bot? ¿prueba?) — Dile a Claude tus convenciones de antemano: 'excluye filas donde deleted_at IS NOT NULL' etc.

Combinar con: notion

Diagnosticar por qué una consulta es lenta y sugerir índices

👤 Ingenieros de backend, DBAs ⏱ ~15 min intermediate

Cuándo usarlo: Tienes una consulta que es más lenta de lo que debería ser. Quieres un segundo par de ojos que no se canse de leer la salida de EXPLAIN ANALYZE.

Flujo

Obtén el plan de consulta

Ejecuta EXPLAIN ANALYZE en esta consulta: [pega]. Cuéntame qué está haciendo el planificador.✓ Copiado

→ Explicación paso a paso del plan
Identifica el factor de costo

¿Qué paso es responsable de la mayor parte del costo? ¿Es un escaneo secuencial, un orden de JOIN incorrecto o un filtrado costoso?✓ Copiado

→ Nodo específico identificado con la razón
Sugiere un índice o una reescritura

Sugiere el cambio más pequeño para hacer esto rápido. Prefiere añadir un índice a reescribir la consulta, pero solo si el índice sería útil para >1 consulta.✓ Copiado

→ Sentencia CREATE INDEX concreta O consulta reescrita

Resultado: Una consulta indexada o reescrita, con razonamiento, que puedas verificar ejecutando EXPLAIN nuevamente.

Errores comunes

EXPLAIN en un conjunto de datos no representativo (BD de dev pequeña) produce planes engañosos — Siempre ejecuta EXPLAIN contra una base de datos con datos con forma de producción; de lo contrario, el plan es ficción
Añadir un índice parece gratis pero ralentiza las escrituras — Dile a Claude que verifique que el índice se usaría verificando con EXPLAIN ANTES de pedirte que lo añada

Combinar con: sentry

Auditar una tabla para problemas de calidad de datos

👤 Ingenieros de datos, cualquiera que herede un esquema desconocido ⏱ ~25 min intermediate

Cuándo usarlo: Estás a punto de construir una característica sobre una tabla que no diseñaste y sospechas que tiene problemas.

Flujo

Ejecuta una batería de comprobaciones de NULL / duplicados / huérfanos

Para la tabla orders: cuenta valores NULL por columna, cuenta filas duplicadas por alguna clave natural (p.ej. (user_id, stripe_payment_intent_id)), cuenta filas con claves externas apuntando a filas padre eliminadas.✓ Copiado

→ Conteos de problemas por comprobación
Comprueba peculiaridades en la distribución de valores

¿Cuál es la distribución de percentiles, mínimo y máximo para total_cents? ¿Hay sospechosamente muchas filas con valores 0 o negativos?✓ Copiado

→ Estadísticas de distribución, valores atípicos marcados
Verifica contra las reglas de negocio esperadas

Cada pedido 'completado' debe tener un paid_at no nulo. ¿Hay excepciones?✓ Copiado

→ Conteo de violaciones + IDs de muestra

Resultado: Una lista corta de bugs concretos de integridad de datos, cada uno con un conteo y una ruta de corrección.

Errores comunes

Algunos 'problemas' son artefactos históricos intencionales (migraciones de datos) — Siempre confirma con alguien que conozca el historial antes de asumir que es un bug

Generar automáticamente documentación de esquema para tu equipo

👤 Líderes técnicos incorporando nuevos ingenieros ⏱ ~20 min beginner

Cuándo usarlo: Tu BD tiene 40 tablas, el wiki tiene 0. Los nuevos contratados siguen preguntando '¿cuál es esta columna?'

Flujo

Obtén todas las tablas y sus esquemas

Lista cada tabla en el esquema público. Para cada una, dame columnas, tipos, nulabilidad, valores por defecto y claves externas.✓ Copiado

→ Volcado de esquema completo
Infiere el propósito de la nomenclatura + datos de muestra

Para cada tabla, toma muestras de 3 filas y escribe una descripción de un párrafo de lo que esta tabla representa en nuestro negocio.✓ Copiado

→ Explicación en prosa por tabla
Marca tablas desconocidas / sospechosas

¿Hay tablas que se vean sin usar o de las que no puedas inferir un propósito? Lístalas para que pueda preguntar al autor original.✓ Copiado

→ Lista honesta 'No sé qué son estas'

Resultado: Un documento Markdown que tu equipo pueda poner en Notion o en un wiki — cubriendo el 80% de lo que los nuevos contratados necesitan saber.

Errores comunes

Muestreo de datos sensibles (PII) en el contexto del LLM — Para tablas con PII, pide a Claude que describa solo esquemas sin muestrear filas

Combinar con: notion · filesystem

Calcular resultados de prueba A/B a partir de datos de eventos brutos

👤 Analistas de producto, ingenieros de crecimiento ⏱ ~30 min advanced

Cuándo usarlo: Ejecutaste un experimento, los datos están en tu BD y quieres números de significancia sin escribir SQL a mano.

Requisitos previos

Tabla de eventos con asignación de experimento + eventos de conversión — Esquema estándar: events(user_id, experiment, variant, timestamp), conversions(user_id, type, timestamp)

Flujo

Calcula la tasa de conversión por variante

Para el experimento 'checkout-redesign-2026': ¿cuántos usuarios fueron asignados a cada variante y cuál fue la tasa de conversión (por [tu evento de conversión]) por variante?✓ Copiado

→ Tabla por variante con tasas
Calcula la significancia estadística

Calcula el valor p de chi-cuadrado para la diferencia entre control y tratamiento. ¿Es el resultado estadísticamente significativo en p < 0.05?✓ Copiado

→ valor p con veredicto
Verifica la cordura de los números

¿Son los tamaños de muestra equilibrados? ¿Se ejecutó el experimento lo suficientemente largo? ¿Hay segmentos donde el resultado se invierte?✓ Copiado

→ Comprobación de salud, no solo valor p

Resultado: Una lectura de prueba A/B estadísticamente defendible con el SQL, los números y los matices.

Errores comunes

Observar los resultados antes del tamaño de muestra predefinido genera falsos positivos — Haz que Claude verifique si la prueba alcanzó su tamaño de muestra objetivo antes de calcular la significancia

Combinar con: notion

Combinaciones

Combínalo con otros MCPs para multiplicar por 10

postgres + notion

Ejecuta una consulta, publica resultados como tabla de Notion para partes interesadas sin acceso a BD

Consulta nuestros 10 clientes principales por ingresos de por vida este trimestre y luego crea una página de Notion en 'Informes de ventas' con los resultados como tabla formateada.✓ Copiado

postgres + sentry

Referenciar cruzadamente el estado de BD con errores — cuando un error menciona un ID de registro, búscalo

El problema de Sentry WEB-3a91 menciona order_id 99214. Busca ese pedido y dime si algo en los datos de la fila podría explicar el fallo.✓ Copiado

postgres + filesystem

Exporta resultados de consulta como CSV/JSON para uso posterior

Ejecuta mi consulta de cohorte de abandono y guarda el resultado como /reports/churn-2026-04.csv.✓ Copiado

Herramientas

Lo que expone este MCP

Herramienta	Entradas	Cuándo llamar	Coste
list_tables	schema?: str	Primer paso en cualquier sesión — descubre el esquema	free
describe_table	table: str, schema?: str	Obtén la estructura completa de una tabla específica antes de consultar	free
query	sql: str	Ejecuta cualquier SQL de solo lectura — solo SELECT	depends on query

Coste y límites

Lo que cuesta ejecutarlo

Cuota de API: Limitado por el límite de conexión de tu BD y el tiempo de espera de consulta
Tokens por llamada: Consultas de esquema: ~500 tokens. Conjuntos de resultados: depende del conteo de filas — limita con LIMIT
Monetario: Gratis — los costos son lo que ya es tu factura de alojamiento de BD
Consejo: Siempre establece un statement_timeout en la conexión (p.ej. ?options=-c%20statement_timeout%3D30000) para que una consulta descontrolada no pueda derribar tu BD.

Seguridad

Permisos, secretos, alcance

Ámbitos mínimos: SELECT en las tablas que quieras exponer

Almacenamiento de credenciales: Cadena de conexión en variable de env. Usa un rol dedicado de solo lectura: CREATE ROLE claude_readonly LOGIN PASSWORD '...'; GRANT SELECT ON ALL TABLES IN SCHEMA public TO claude_readonly;

Salida de datos: Todas las consultas a tu BD; filas de resultados enviadas a cualquier proveedor de LLM que uses

No conceder nunca: INSERT UPDATE DELETE DROP TRUNCATE ALTER

Incluso las consultas de solo lectura pueden ser costosas — envuelve con SET statement_timeout si te conectas a prod.
Usa una cadena de conexión de réplica de lectura en producción.

Resolución de problemas

Errores comunes y soluciones

FATAL: autenticación de contraseña fallida

Comprueba la cadena de conexión. Causa común: caracteres especiales en contraseña no codificados como URL.

Verificar: psql 'postgres://...' -c 'SELECT 1'

no pg_hba.conf entrada / SSL requerido

Añade ?sslmode=require a la cadena de conexión. La mayoría de Postgres gestionado requiere SSL.

permiso denegado para tabla X

El rol no tiene SELECT en esa tabla. Ejecuta GRANT SELECT ON X TO claude_readonly.

Verificar: psql -c '\dp X'

cancelando sentencia debido a agotamiento del tiempo de espera de sentencia

La consulta era demasiado lenta. Optimízala (añade un índice, estrecha la cláusula WHERE) o aumenta el tiempo de espera para esa conexión.

Alternativas

Postgres vs otros

Alternativa	Cuándo usarla	Contrapartida
Supabase MCP	Estás en Supabase — obtén gestión de proyectos completa más SQL	Incluye acceso de escritura; menos seguro para prod
Neon MCP	Estás en Neon — añade ramificación para prueba de migración segura	Las características específicas de Neon solo funcionan en BDs de Neon
dbHub	Necesitas soporte de múltiples bases de datos (Postgres, MySQL, MongoDB, etc.) en un MCP	Más nuevo; soporta más BDs pero cada integración es más superficial
sqlite MCP	BD basada en archivo local en lugar de servidor	Sin acceso concurrente, sin red, pero sin configuración

Más

Recursos

📖 Lee el README oficial en GitHub

🐙 Ver issues abiertas

🔍 Ver todos los 400+ servidores MCP y Skills