Postgres MCP Pro

Un servidor MCP para PostgreSQL que proporciona ajuste de índices, planes de explicación, verificaciones de estado y ejecución segura de SQL.

GitHub
3.4k
Prueba este MCPPatrocinado

Documentación

Postgres MCP Pro Logo

License: MIT PyPI - Version Discord Twitter Follow Contributors

Un servidor MCP de Postgres con ajuste de índices, planes de explicación, comprobaciones de salud y ejecución segura de SQL.

Descripción general

Postgres MCP Pro es un servidor de código abierto del Protocolo de Contexto de Modelo (MCP) diseñado para apoyarte a ti y a tus agentes de IA durante todo el proceso de desarrollo, desde la codificación inicial, pasando por las pruebas y el despliegue, hasta el ajuste y mantenimiento en producción.

Postgres MCP Pro hace mucho más que envolver una conexión de base de datos.

Las funciones incluyen:

  • 🔍 Salud de la base de datos: analiza la salud de los índices, la utilización de conexiones, la caché de búferes, la salud de vacuum, los límites de secuencias, el retraso de replicación y más.
  • ⚡ Ajuste de índices: explora miles de índices posibles para encontrar la mejor solución para tu carga de trabajo, utilizando algoritmos de nivel industrial.
  • 📈 Planes de consulta: valida y optimiza el rendimiento revisando los planes EXPLAIN y simulando el impacto de índices hipotéticos.
  • 🧠 Inteligencia de esquema: generación de SQL consciente del contexto basada en un conocimiento detallado del esquema de la base de datos.
  • 🛡️ Ejecución segura de SQL: control de acceso configurable, incluido el soporte para modo de solo lectura y análisis seguro de SQL, lo que lo hace utilizable tanto en desarrollo como en producción.

Postgres MCP Pro admite tanto el transporte de Entrada/Salida estándar (stdio) como el de Eventos enviados por el servidor (SSE), para ofrecer flexibilidad en diferentes entornos.

Para obtener más información sobre por qué creamos Postgres MCP Pro, consulta nuestra publicación de blog de lanzamiento.

Demo

De inutilizable a extremadamente rápido

  • Desafío: Generamos una aplicación de películas con un asistente de IA, pero el código ORM de SQLAlchemy funcionaba terriblemente lento.
  • Solución: Usando Postgres MCP Pro con Cursor, solucionamos los problemas de rendimiento en minutos.

Lo que hicimos:

  • 🚀 Corregimos el rendimiento, incluidas las consultas ORM, la indexación y el almacenamiento en caché
  • 🛠️ Corregimos una página rota, indicando al agente que explorara los datos, corrigiera las consultas y añadiera contenido relacionado.
  • 🧠 Mejoramos las mejores películas, explorando los datos y corrigiendo la consulta ORM para mostrar resultados más relevantes.

Mira el vídeo a continuación o lee el relato detallado.

https://github.com/user-attachments/assets/24e05745-65e9-4998-b877-a368f1eadc13

Inicio rápido

Requisitos previos

Antes de empezar, asegúrate de tener:

  1. Credenciales de acceso para tu base de datos.
  2. Docker o Python 3.12 o superior.

Credenciales de acceso

Puedes confirmar que tus credenciales de acceso son válidas usando psql o una herramienta gráfica como pgAdmin.

Docker o Python

La elección de usar Docker o Python es tuya. Generalmente recomendamos Docker porque los usuarios de Python pueden encontrarse con más problemas específicos del entorno. Sin embargo, a menudo tiene sentido usar el método con el que estés más familiarizado.

Instalación

Elige uno de los siguientes métodos para instalar Postgres MCP Pro:

Opción 1: Usar Docker

Descarga la imagen Docker del servidor MCP de Postgres MCP Pro. Esta imagen contiene todas las dependencias necesarias, lo que proporciona una forma fiable de ejecutar Postgres MCP Pro en una variedad de entornos.

docker pull crystaldba/postgres-mcp

Opción 2: Usar Python

Si tienes pipx instalado, puedes instalar Postgres MCP Pro con:

pipx install postgres-mcp

De lo contrario, instala Postgres MCP Pro con uv:

uv pip install postgres-mcp

Si necesitas instalar uv, consulta las instrucciones de instalación de uv.

Configura tu asistente de IA

Proporcionamos instrucciones completas para configurar Postgres MCP Pro con Claude Desktop. Muchos clientes MCP tienen archivos de configuración similares; puedes adaptar estos pasos para que funcionen con el cliente de tu elección.

Configuración de Claude Desktop

Tendrás que editar el archivo de configuración de Claude Desktop para añadir Postgres MCP Pro. La ubicación de este archivo depende de tu sistema operativo:

  • MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%/Claude/claude_desktop_config.json

También puedes usar el elemento de menú Settings en Claude Desktop para localizar el archivo de configuración.

Ahora editarás la sección mcpServers del archivo de configuración.

Si estás usando Docker
{
  "mcpServers": {
    "postgres": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "DATABASE_URI",
        "crystaldba/postgres-mcp",
        "--access-mode=unrestricted"
      ],
      "env": {
        "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
      }
    }
  }
}

La imagen Docker de Postgres MCP Pro reasignará automáticamente el nombre de host localhost para que funcione desde dentro del contenedor.

  • MacOS/Windows: usa host.docker.internal automáticamente
  • Linux: usa 172.17.0.1 o la dirección de host adecuada automáticamente
Si estás usando uvx
{
  "mcpServers": {
    "postgres": {
      "command": "uvx",
      "args": [
        "postgres-mcp",
        "--access-mode=unrestricted"
      ],
      "env": {
        "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
      }
    }
  }
}
Si estás usando pipx
{
  "mcpServers": {
    "postgres": {
      "command": "postgres-mcp",
      "args": [
        "--access-mode=unrestricted"
      ],
      "env": {
        "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
      }
    }
  }
}
Si estás usando uv
{
  "mcpServers": {
    "postgres": {
      "command": "uv",
      "args": [
        "run",
        "postgres-mcp",
        "--access-mode=unrestricted"
      ],
      "env": {
        "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
      }
    }
  }
}
URI de conexión

Reemplaza postgresql://... con tu URI de conexión de base de datos Postgres.

Modo de acceso

Postgres MCP Pro admite múltiples modos de acceso para darte control sobre las operaciones que el agente de IA puede realizar en la base de datos:

  • Modo sin restricciones: permite acceso completo de lectura/escritura para modificar datos y esquema. Es adecuado para entornos de desarrollo.
  • Modo restringido: limita las operaciones a transacciones de solo lectura e impone restricciones en la utilización de recursos (actualmente solo el tiempo de ejecución). Es adecuado para entornos de producción.

Para usar el modo restringido, reemplaza --access-mode=unrestricted con --access-mode=restricted en los ejemplos de configuración anteriores.

Otros clientes MCP

Muchos clientes MCP tienen archivos de configuración similares a los de Claude Desktop, y puedes adaptar los ejemplos anteriores para que funcionen con el cliente de tu elección.

  • Si estás usando Cursor, puedes navegar desde Command Palette hasta Cursor Settings y luego abrir la pestaña MCP para acceder al archivo de configuración.
  • Si estás usando Windsurf, puedes navegar desde Command Palette hasta Open Windsurf Settings Page para acceder al archivo de configuración.
  • Si estás usando Goose, ejecuta goose configure y luego selecciona Add Extension.
  • Si estás usando Qodo Gen, abre el panel de Chat, haz clic en Connect more tools, haz clic en + Add new MCP y luego añade la nueva configuración.

Transporte SSE

Postgres MCP Pro admite el transporte SSE, que permite que varios clientes MCP compartan un solo servidor, posiblemente remoto. Para usar el transporte SSE, debes iniciar el servidor con la opción --transport=sse.

Por ejemplo, con Docker ejecuta:

docker run -p 8000:8000 \
  -e DATABASE_URI=postgresql://username:password@localhost:5432/dbname \
  crystaldba/postgres-mcp --access-mode=unrestricted --transport=sse

Luego actualiza la configuración de tu cliente MCP para llamar al servidor MCP. Por ejemplo, en mcp.json de Cursor o en cline_mcp_settings.json de Cline puedes poner:

{
    "mcpServers": {
        "postgres": {
            "type": "sse",
            "url": "http://localhost:8000/sse"
        }
    }
}

Para Windsurf, el formato en mcp_config.json es ligeramente diferente:

{
    "mcpServers": {
        "postgres": {
            "type": "sse",
            "serverUrl": "http://localhost:8000/sse"
        }
    }
}

Instalación de extensiones de Postgres (opcional)

Para habilitar el ajuste de índices y el análisis completo del rendimiento, debes cargar las extensiones pg_stat_statements y hypopg en tu base de datos.

  • La extensión pg_stat_statements permite a Postgres MCP Pro analizar las estadísticas de ejecución de consultas. Por ejemplo, esto le permite entender qué consultas se ejecutan lentamente o consumen recursos significativos.
  • La extensión hypopg permite a Postgres MCP Pro simular el comportamiento del planificador de consultas de Postgres después de añadir índices.

Instalación de extensiones en AWS RDS, Azure SQL o Google Cloud SQL

Si tu base de datos Postgres se ejecuta en un servicio gestionado de un proveedor de nube, las extensiones pg_stat_statements y hypopg ya deberían estar disponibles en el sistema. En este caso, puedes ejecutar comandos CREATE EXTENSION usando un rol con privilegios suficientes:

CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
CREATE EXTENSION IF NOT EXISTS hypopg;

Instalación de extensiones en Postgres autogestionado

Si gestionas tu propia instalación de Postgres, es posible que necesites hacer trabajo adicional. Antes de cargar la extensión pg_stat_statements, debes asegurarte de que esté listada en shared_preload_libraries en el archivo de configuración de Postgres. La extensión hypopg también puede requerir instalación adicional a nivel de sistema (por ejemplo, mediante tu gestor de paquetes) porque no siempre se incluye con Postgres.

Ejemplos de uso

Obtener una visión general de la salud de la base de datos

Pregunta:

Comprueba la salud de mi base de datos e identifica cualquier problema.

Analizar consultas lentas

Pregunta:

¿Cuáles son las consultas más lentas de mi base de datos? ¿Y cómo puedo acelerarlas?

Obtener recomendaciones sobre cómo acelerar las cosas

Pregunta:

Mi aplicación es lenta. ¿Cómo puedo hacerla más rápida?

Generar recomendaciones de índices

Pregunta:

Analiza la carga de trabajo de mi base de datos y sugiere índices para mejorar el rendimiento.

Optimizar una consulta específica

Pregunta:

Ayúdame a optimizar esta consulta: SELECT * FROM orders JOIN customers ON orders.customer_id = customers.id WHERE orders.created_at > '2023-01-01';

API del servidor MCP

El estándar MCP define varios tipos de endpoints: herramientas, recursos, prompts y otros.

Postgres MCP Pro proporciona funcionalidad únicamente mediante herramientas MCP. Elegimos este enfoque porque el ecosistema de clientes MCP tiene un amplio soporte para las herramientas MCP. Esto contrasta con el enfoque de otros servidores MCP de Postgres, incluido el servidor MCP de Postgres de referencia, que utilizan recursos MCP para exponer información del esquema.

Herramientas de Postgres MCP Pro:

Nombre de la herramientaDescripción
list_schemasEnumera todos los esquemas de base de datos disponibles en la instancia de PostgreSQL.
list_objectsEnumera los objetos de base de datos (tablas, vistas, secuencias, extensiones) dentro de un esquema especificado.
get_object_detailsProporciona información sobre un objeto de base de datos específico, por ejemplo, las columnas, restricciones e índices de una tabla.
execute_sqlEjecuta sentencias SQL en la base de datos, con limitaciones de solo lectura cuando se conecta en modo restringido.
explain_queryObtiene el plan de ejecución de una consulta SQL que describe cómo PostgreSQL la procesará y expone el modelo de costes del planificador de consultas. Se puede invocar con índices hipotéticos para simular el comportamiento después de añadir índices.
get_top_queriesInforma de las consultas SQL más lentas según el tiempo total de ejecución utilizando datos de pg_stat_statements.
analyze_workload_indexesAnaliza la carga de trabajo de la base de datos para identificar consultas que consumen muchos recursos y luego recomienda índices óptimos para ellas.
analyze_query_indexesAnaliza una lista de consultas SQL específicas (hasta 10) y recomienda índices óptimos para ellas.
analyze_db_healthRealiza comprobaciones de salud exhaustivas que incluyen: tasas de acierto de la caché de búferes, salud de las conexiones, validación de restricciones, salud de los índices (duplicados/sin usar/no válidos), límites de secuencias y salud de vacuum.

Proyectos relacionados

Servidores MCP de Postgres

  • Query MCP. Un servidor MCP para Supabase Postgres con una arquitectura de seguridad de tres niveles y soporte para la API de gestión de Supabase.
  • PG-MCP. Un servidor MCP para PostgreSQL con opciones de conexión flexibles, planes de explicación, contexto de extensiones y más.
  • Servidor MCP de PostgreSQL de referencia. Una implementación simple de servidor MCP que expone información del esquema como recursos MCP y ejecuta consultas de solo lectura.
  • Servidor MCP de Supabase Postgres. Este servidor MCP proporciona funciones de gestión de Supabase y es mantenido activamente por la comunidad de Supabase.
  • Servidor MCP de Nile. Un servidor MCP que proporciona acceso a la API de gestión del servicio Postgres multiinquilino de Nile.
  • Servidor MCP de Neon. Un servidor MCP que proporciona acceso a la API de gestión del servicio Postgres serverless de Neon.
  • Servidor MCP de Wren. Proporciona un motor semántico que impulsa la inteligencia empresarial para Postgres y otras bases de datos.

Herramientas DBA (incluyendo ofertas comerciales)

  • Aiven Database Optimizer. Una herramienta que proporciona análisis holístico de la carga de trabajo de la base de datos, optimizaciones de consultas y otras mejoras de rendimiento.
  • dba.ai. Un asistente de administración de bases de datos impulsado por IA que se integra con GitHub para resolver problemas de código.
  • pgAnalyze. Una plataforma integral de monitoreo y análisis para identificar cuellos de botella de rendimiento, optimizar consultas y alertas en tiempo real.
  • Postgres.ai. Una experiencia de chat interactiva que combina una extensa base de conocimientos de Postgres y GPT-4.
  • Xata Agent. Un agente de IA de código abierto que monitorea automáticamente la salud de la base de datos, diagnostica problemas y proporciona recomendaciones utilizando razonamiento impulsado por LLM y manuales de operación.

Utilidades de Postgres

  • Dexter. Una herramienta para generar y probar índices hipotéticos en PostgreSQL.
  • PgHero. Un panel de rendimiento para Postgres, con recomendaciones. Postgres MCP Pro incorpora comprobaciones de salud de PgHero.
  • PgTune. Heurísticas para ajustar la configuración de Postgres.

Preguntas Frecuentes

¿En qué se diferencia Postgres MCP Pro de otros servidores MCP de Postgres? Hay muchos servidores MCP que permiten a un agente de IA ejecutar consultas contra una base de datos Postgres. Postgres MCP Pro también hace eso, pero además añade herramientas para comprender y mejorar el rendimiento de tu base de datos Postgres. Por ejemplo, implementa una versión del Algoritmo Anytime del Asesor de Ajuste de Bases de Datos para Microsoft SQL Server, un algoritmo industrial moderno y robusto para el ajuste automático de índices.

Postgres MCP ProOtros servidores MCP de Postgres
✅ Comprobaciones de salud de base de datos deterministas❌ Consultas de salud generadas por LLM no reproducibles
✅ Estrategias de búsqueda de indexación basadas en principios❌ Suposiciones de IA generativa para mejoras de indexación
✅ Análisis de carga de trabajo para encontrar los principales problemas❌ Análisis de problemas inconsistente
✅ Simula mejoras de rendimiento❌ Pruébalo tú mismo y mira si funciona

Postgres MCP Pro complementa la IA generativa añadiendo herramientas deterministas y algoritmos de optimización clásicos. La combinación es a la vez fiable y flexible.

¿Por qué se necesitan herramientas MCP cuando el LLM puede razonar, generar SQL, etc.? Los LLM son invaluables para tareas que implican ambigüedad, razonamiento o lenguaje natural. En comparación con el código procedural, sin embargo, pueden ser lentos, costosos, no deterministas y a veces producir resultados poco fiables. En el caso del ajuste de bases de datos, tenemos algoritmos bien establecidos, desarrollados durante décadas, que han demostrado funcionar. Postgres MCP Pro te permite combinar lo mejor de ambos mundos al emparejar LLM con algoritmos de optimización clásicos y otras herramientas procedurales.

¿Cómo se prueba Postgres MCP Pro? Las pruebas son críticas para garantizar que Postgres MCP Pro sea fiable y preciso. Estamos construyendo un conjunto de cargas de trabajo adversarias generadas por IA diseñadas para desafiar a Postgres MCP Pro y asegurar que funcione bajo una amplia variedad de escenarios.

¿Qué versiones de Postgres se soportan? Nuestras pruebas actualmente se centran en Postgres 15, 16 y 17. Planeamos soportar las versiones 13 a 17 de Postgres.

¿Quién creó este proyecto? Este proyecto es creado y mantenido por Crystal DBA.

Hoja de ruta

Pendiente

Tú y tus necesidades son un factor crítico para lo que construimos. Cuéntanos qué te gustaría ver abriendo un issue o un pull request. También puedes contactarnos en Discord.

Notas Técnicas

Esta sección incluye una visión general de alto nivel de las consideraciones técnicas que influyeron en el diseño de Postgres MCP Pro.

Ajuste de Índices

Los desarrolladores saben que los índices faltantes son una de las causas más comunes de problemas de rendimiento en bases de datos. Los índices proporcionan métodos de acceso que permiten a Postgres localizar rápidamente los datos necesarios para ejecutar una consulta. Cuando las tablas son pequeñas, los índices marcan poca diferencia, pero a medida que el tamaño de los datos crece, la diferencia en complejidad algorítmica entre un escaneo de tabla y una búsqueda por índice se vuelve significativa (típicamente O(n) vs O(log n), potencialmente más si hay uniones en múltiples tablas).

La generación de índices sugeridos en Postgres MCP Pro procede en varias etapas:

  1. Identificar consultas SQL que necesitan ajuste. Si sabes que tienes un problema con una consulta SQL específica, puedes proporcionarla. Postgres MCP Pro también puede analizar la carga de trabajo para identificar objetivos de ajuste de índices. Para ello, se basa en la extensión pg_stat_statements, que registra el tiempo de ejecución y el consumo de recursos de cada consulta.

    Una consulta es candidata para el ajuste de índices si es un consumidor principal de recursos, ya sea por ejecución individual o en agregado. Actualmente, usamos el tiempo de ejecución como proxy del consumo acumulado de recursos, pero también podría tener sentido observar recursos específicos, por ejemplo, el número de bloques accedidos o el número de bloques leídos desde disco. La herramienta analyze_query_workload se centra en consultas lentas, utilizando el tiempo medio por ejecución con umbrales para el número de ejecuciones y el tiempo medio de ejecución. Los agentes también pueden llamar a get_top_queries, que acepta un parámetro para tiempo medio vs. tiempo total de ejecución, y luego pasar estas consultas a analyze_query_indexes para obtener recomendaciones de índices.

    Los sistemas sofisticados de ajuste de índices utilizan "compresión de carga de trabajo" para producir un subconjunto representativo de consultas que refleje las características de la carga de trabajo en su conjunto, reduciendo el problema para los algoritmos posteriores. Postgres MCP Pro realiza una forma limitada de compresión de carga de trabajo normalizando las consultas para que las generadas a partir de la misma plantilla aparezcan como una sola. Pondera cada consulta por igual, una simplificación que funciona cuando los beneficios de la indexación son grandes.

  2. Generar índices candidatos Una vez que tenemos una lista de consultas SQL que queremos mejorar mediante indexación, generamos una lista de índices que podríamos añadir. Para ello, analizamos el SQL e identificamos cualquier columna utilizada en filtros, uniones, agrupaciones u ordenaciones.

    Para generar todos los índices posibles, necesitamos considerar combinaciones de estas columnas, porque Postgres soporta índices multicolumna. En la implementación actual, incluimos solo una permutación de cada índice multicolumna posible, seleccionada al azar. Hacemos esta simplificación para reducir el espacio de búsqueda porque las permutaciones a menudo tienen un rendimiento equivalente. Sin embargo, esperamos mejorar en esta área.

  3. Buscar la configuración óptima de índices. Nuestro objetivo es encontrar la combinación de índices que equilibre de manera óptima los beneficios de rendimiento con los costos de almacenar y mantener esos índices. Estimamos la mejora de rendimiento utilizando las capacidades de "qué pasaría si" proporcionadas por la extensión hypopg. Esto simula cómo el optimizador de consultas de Postgres ejecutará una consulta después de la adición de índices, e informa cambios basados en el modelo de costos real de Postgres.

    Un desafío es que generar planes de consulta generalmente requiere conocer los valores de parámetros específicos utilizados en la consulta. La normalización de consultas, que es necesaria para reducir las consultas bajo consideración, elimina las constantes de parámetros. Los valores de parámetros proporcionados mediante variables de enlace tampoco están disponibles para nosotros.

    Para abordar este problema, producimos constantes realistas que podemos proporcionar como parámetros muestreando las estadísticas de la tabla. En la versión 16, Postgres añadió funcionalidad de plan de explicación genérico, pero tiene limitaciones, por ejemplo en torno a las cláusulas LIKE, que nuestra implementación no tiene.

    La estrategia de búsqueda es crítica porque evaluar todas las combinaciones posibles de índices solo es factible en situaciones simples. Esto es lo que más distingue a los diversos enfoques de indexación. Adaptando el enfoque del algoritmo Anytime de Microsoft, empleamos una estrategia de búsqueda voraz, es decir, encontrar la mejor solución de un índice, luego encontrar el mejor índice para añadir a esa para producir una solución de dos índices. Nuestra búsqueda termina cuando se agota el presupuesto de tiempo o cuando una ronda de exploración no produce ganancias por encima del umbral mínimo de mejora del 10%.

  4. Análisis de costo-beneficio. Cuando se presentan dos alternativas de indexación, una que produce mejor rendimiento y otra que requiere más espacio, ¿cómo decidimos cuál elegir? Tradicionalmente, los asesores de índices piden un presupuesto de almacenamiento y optimizan el rendimiento con respecto a ese presupuesto de almacenamiento. También tomamos un presupuesto de almacenamiento, pero realizamos un análisis de costo-beneficio a lo largo de la optimización.

    Enmarcamos esto como el problema de seleccionar un punto a lo largo del frente de Pareto—el conjunto de opciones para las cuales mejorar una métrica de calidad necesariamente empeora otra. En un mundo ideal, podríamos querer evaluar el costo del almacenamiento y el beneficio de un mejor rendimiento en términos monetarios. Sin embargo, hay un enfoque más simple y práctico: observar los cambios en términos relativos. La mayoría de las personas estarían de acuerdo en que una mejora de rendimiento de 100x vale la pena, incluso si el costo de almacenamiento es 2x. En nuestra implementación, usamos un parámetro configurable para establecer este umbral. Por defecto, requerimos que el cambio en el log (base 10) de la mejora de rendimiento sea 2 veces la diferencia en el log del costo de espacio. Esto equivale a permitir un aumento máximo de 10x en espacio para una mejora de rendimiento de 100x.

Nuestra implementación está más estrechamente relacionada con el Algoritmo Anytime que se encuentra en Microsoft SQL Server. En comparación con Dexter, una herramienta de indexación automática para Postgres, buscamos en un espacio más grande y usamos heurísticas diferentes. Esto nos permite generar mejores soluciones a costa de un tiempo de ejecución más largo.

También mostramos el trabajo realizado en cada ronda de búsqueda, incluyendo una comparación de los planes de consulta antes y después de la adición de cada índice. Esto le da al LLM contexto adicional que puede usar al responder a las recomendaciones de indexación.

Experimental: Ajuste de Índices por LLM

Postgres MCP Pro incluye una característica experimental de ajuste de índices basada en Optimización por LLM. En lugar de usar heurísticas para explorar posibles configuraciones de índices, proporcionamos el esquema de la base de datos y los planes de consulta a un LLM y le pedimos que proponga configuraciones de índices. Luego usamos hypopg para predecir el rendimiento con los índices propuestos, y luego alimentamos esos resultados de vuelta al LLM para producir un nuevo conjunto de sugerencias. Repetimos este proceso hasta que múltiples rondas de iteración no produzcan mejoras adicionales.

La optimización de índices por LLM tiene ventajas cuando el espacio de búsqueda de índices es grande, o cuando se necesitan considerar índices con muchas columnas. Al igual que los enfoques tradicionales basados en búsqueda, depende de la precisión de las predicciones de rendimiento de hypopg.

Para realizar la optimización de índices por LLM, debes proporcionar una clave API de OpenAI configurando la variable de entorno OPENAI_API_KEY.

Salud de la Base de Datos

Las comprobaciones de salud de la base de datos identifican oportunidades de ajuste y necesidades de mantenimiento antes de que se conviertan en problemas críticos. En la versión actual, Postgres MCP Pro adapta las comprobaciones de salud de la base de datos directamente de PgHero. Estamos trabajando para validar completamente estas comprobaciones y podemos ampliarlas en el futuro.

  • Salud de índices. Busca índices no utilizados, índices duplicados e índices que están inflados. Los índices inflados hacen un uso ineficiente de las páginas de la base de datos. El autovacío de Postgres limpia las entradas de índice que apuntan a tuplas muertas y marca las entradas como reutilizables. Sin embargo, no compacta las páginas de índice y, eventualmente, las páginas de índice pueden contener pocas referencias a tuplas vivas.
  • Tasa de aciertos de caché de búfer. Mide la proporción de lecturas de base de datos que se sirven desde la caché de búfer en lugar del disco. Una tasa de aciertos de caché de búfer baja debe investigarse, ya que a menudo no es rentable y conduce a un rendimiento degradado de la aplicación.
  • Salud de conexiones. Verifica el número de conexiones a la base de datos e informa sobre su utilización. El mayor riesgo es quedarse sin conexiones, pero un alto número de conexiones inactivas o bloqueadas también puede indicar problemas.
  • Salud de vacío. El vacío es importante por muchas razones. Una crítica es prevenir el envolvente del ID de transacción, que puede hacer que la base de datos deje de aceptar escrituras. El mecanismo de control de concurrencia multiversión (MVCC) de Postgres requiere un ID de transacción único para cada transacción. Sin embargo, debido a que Postgres usa un entero con signo de 32 bits para los IDs de transacción, necesita reutilizar los IDs de transacción después de un máximo de 2 mil millones de transacciones. Para hacer esto, "congela" los IDs de transacción de transacciones históricas, estableciéndolos todos a un valor especial que indica pasado lejano. Cuando los registros se escriben por primera vez en el disco, se escriben con visibilidad para un rango de IDs de transacción. Antes de reutilizar estos IDs de transacción, Postgres debe actualizar cualquier registro en disco, "congelándolos" para eliminar las referencias a los IDs de transacción que se reutilizarán. Esta verificación busca tablas que requieran vacío para prevenir el envolvente del ID de transacción.
  • Salud de replicación. Verifica la salud de la replicación monitoreando el retraso entre el primario y las réplicas, verificando el estado de replicación y rastreando el uso de los slots de replicación.
  • Salud de restricciones. Durante la operación normal, Postgres rechaza cualquier transacción que cause una violación de restricción. Sin embargo, pueden ocurrir restricciones inválidas después de cargar datos o en escenarios de recuperación. Esta verificación busca cualquier restricción inválida.
  • Salud de secuencias. Busca secuencias que estén en riesgo de exceder su valor máximo.

Biblioteca de cliente de Postgres

Postgres MCP Pro usa psycopg3 para conectarse a Postgres usando E/S asíncrona. Internamente, psycopg3 usa la biblioteca libpq para conectarse a Postgres, proporcionando acceso al conjunto completo de características de Postgres y una implementación subyacente totalmente respaldada por la comunidad de Postgres.

Algunos otros servidores MCP basados en Python usan asyncpg, que puede simplificar la instalación al eliminar la dependencia de libpq. Asyncpg también es probablemente más rápido que psycopg3, pero no hemos validado esto nosotros mismos. Puntos de referencia más antiguos reportan una brecha de rendimiento mayor, lo que sugiere que el psycopg3 más nuevo ha cerrado la brecha a medida que madura.

Equilibrando estas consideraciones, seleccionamos psycopg3 sobre asyncpg. Seguimos abiertos a revisar esta decisión en el futuro.

Configuración de conexión

Como el Servidor MCP de PostgreSQL de referencia, Postgres MCP Pro toma la información de conexión de Postgres al inicio. Esto es conveniente para usuarios que siempre se conectan a la misma base de datos, pero puede ser engorroso cuando los usuarios cambian de base de datos.

Un enfoque alternativo, adoptado por PG-MCP, es proporcionar los detalles de conexión a través de llamadas a herramientas MCP en el momento de uso. Esto es más conveniente para usuarios que cambian de base de datos y permite que un solo servidor MCP admita simultáneamente a múltiples usuarios finales.

Debe haber un mejor enfoque que cualquiera de estos. Ambos tienen debilidades de seguridad: pocos clientes MCP almacenan la configuración del servidor MCP de forma segura (una excepción es Goose), y las credenciales proporcionadas a través de herramientas MCP se pasan a través del LLM y se almacenan en el historial de chat. Ambos también tienen problemas de usabilidad en algunos escenarios.

Información de esquema

El propósito de la herramienta de información de esquema es proporcionar al agente de IA que llama la información que necesita para generar SQL correcto y eficiente. Por ejemplo, supongamos que un usuario pregunta: "¿Cuántos vuelos despegaron de San Francisco y aterrizaron en París durante el año pasado?" El agente de IA necesita encontrar la tabla que almacena los vuelos, las columnas que almacenan el origen y los destinos, y quizás una tabla que mapee entre códigos de aeropuerto y ubicaciones de aeropuertos.

¿Por qué proporcionar herramientas de información de esquema cuando los LLM son generalmente capaces de generar el SQL para recuperar esta información de Postgres directamente?

Nuestra experiencia usando Claude indica que el LLM que llama es muy bueno generando SQL para explorar el esquema de Postgres consultando el catálogo del sistema de Postgres y el esquema de información (una vista de metadatos de base de datos estandarizada por ANSI). Sin embargo, no sabemos si otros LLM lo hacen de manera tan confiable y capaz.

¿Sería mejor proporcionar información de esquema usando recursos MCP en lugar de herramientas MCP?

El Servidor MCP de PostgreSQL de referencia usa recursos para exponer información de esquema en lugar de herramientas. Navegar por los recursos es similar a navegar por un sistema de archivos, por lo que este enfoque es natural en muchos aspectos. Sin embargo, el soporte de recursos está menos extendido que el soporte de herramientas en el ecosistema de clientes MCP (ver clientes de ejemplo). Además, aunque el estándar MCP dice que los recursos pueden ser accedidos tanto por agentes de IA como por humanos usuarios finales, algunos clientes solo admiten la navegación humana del árbol de recursos.

Ejecución de SQL protegida

La IA amplifica los desafíos de larga data de proteger las bases de datos contra una variedad de amenazas, que van desde errores simples hasta ataques sofisticados de actores maliciosos. Ya sea que la amenaza sea accidental o maliciosa, se aplica un marco de seguridad similar, con objetivos que caen en tres categorías: confidencialidad, integridad y disponibilidad. La tensión familiar entre conveniencia y seguridad también es evidente y pronunciada.

El modo de ejecución de SQL protegida de Postgres MCP Pro se centra en la integridad. En el contexto de MCP, nos preocupa principalmente que el SQL generado por LLM cause daños, por ejemplo, modificación o eliminación no intencionada de datos, u otros cambios que podrían eludir el proceso de gestión de cambios de una organización.

La forma más simple de proporcionar integridad es asegurar que todo el SQL ejecutado contra la base de datos sea de solo lectura. Una forma de hacerlo es creando un usuario de base de datos con permisos de solo lectura. Aunque este es un buen enfoque, muchos lo encuentran engorroso en la práctica. Postgres no proporciona una forma de poner una conexión o sesión en modo de solo lectura, por lo que Postgres MCP Pro usa un enfoque más complejo para asegurar la ejecución de SQL de solo lectura sobre una conexión de lectura-escritura.

Postgres MCP Pro proporciona un modo de transacción de solo lectura que previene modificaciones de datos y esquema. Como el Servidor MCP de PostgreSQL de referencia, usamos transacciones de solo lectura para proporcionar ejecución de SQL protegida.

Para hacer este mecanismo robusto, necesitamos asegurar que el SQL no eluda de alguna manera el modo de transacción de solo lectura, por ejemplo, emitiendo una declaración COMMIT o ROLLBACK y luego comenzando una nueva transacción.

Por ejemplo, el LLM puede eludir el modo de transacción de solo lectura emitiendo una declaración ROLLBACK y luego comenzando una nueva transacción. Por ejemplo:

ROLLBACK; DROP TABLE users;

Para prevenir casos como este, analizamos el SQL antes de la ejecución usando la biblioteca pglast. Rechazamos cualquier SQL que contenga declaraciones commit o rollback. Afortunadamente, los lenguajes de procedimientos almacenados populares de Postgres, incluidos PL/pgSQL y PL/Python, no permiten declaraciones COMMIT o ROLLBACK. Si tiene lenguajes de procedimientos almacenados inseguros habilitados en su base de datos, nuestras protecciones de solo lectura podrían ser eludidas.

Actualmente, Postgres MCP Pro proporciona dos niveles de protección para la base de datos, uno en cada extremo del espectro de conveniencia/seguridad.

  • "Sin restricciones" proporciona máxima flexibilidad. Es adecuado para entornos de desarrollo donde la velocidad y la flexibilidad son primordiales, y donde no hay necesidad de proteger datos valiosos o sensibles.
  • "Restringido" proporciona un equilibrio entre flexibilidad y seguridad. Es adecuado para entornos de producción donde la base de datos está expuesta a usuarios no confiables, y donde es importante proteger datos valiosos o sensibles.

El modo sin restricciones se alinea con el enfoque del modo de ejecución automática de Cursor, donde el agente de IA opera con supervisión o aprobaciones humanas limitadas. Esperamos que la ejecución automática se implemente en entornos de desarrollo donde las consecuencias de los errores son bajas, donde las bases de datos no contienen datos valiosos o sensibles, y donde pueden recrearse o restaurarse desde copias de seguridad cuando sea necesario.

Diseñamos el modo restringido para ser conservador, priorizando la seguridad aunque pueda ser inconveniente. El modo restringido se limita a operaciones de solo lectura, y limitamos el tiempo de ejecución de consultas para evitar que consultas de larga duración afecten el rendimiento del sistema. Podemos agregar medidas en el futuro para asegurar que el modo restringido sea seguro de usar con bases de datos de producción.

Desarrollo de Postgres MCP Pro

Las instrucciones a continuación son para desarrolladores que quieren trabajar en Postgres MCP Pro, o usuarios que prefieren instalar Postgres MCP Pro desde el código fuente.

Configuración de desarrollo local

  1. Instalar uv:

    curl -sSL https://astral.sh/uv/install.sh | sh

  2. Clonar el repositorio:

    git clone https://github.com/crystaldba/postgres-mcp.git
cd postgres-mcp

  3. Instalar dependencias:

    uv pip install -e .
uv sync

  4. Ejecutar el servidor:

    uv run postgres-mcp "postgres://user:password@localhost:5432/dbname"