pg_licht

Un servidor MCP de PostgreSQL que expone herramientas de exploración de esquemas.

Ver en github.io

Documentación

Un servidor PostgreSQL MCP de solo lectura para cada base de datos que ejecutes.

pg-licht ofrece a un asistente de IA 76 herramientas y 13 investigaciones guiadas para explorar esquemas, leer estadísticas y diagnosticar servidores en vivo. Nunca puede cambiar tus datos, nunca devuelve filas de tus tablas, y responde por toda una flota desde un solo proceso.

Instalar Explorar las 76 herramientas

76 herramientas de solo lectura en 11 grupos

13 investigaciones guiadas

1 proceso para cualquier número de conexiones

0 sentencias que puedan escribir

14–18 versiones principales de PostgreSQL probadas en cada cambio

Un servidor para toda la flota

Cada herramienta conectada toma un argumento connection, así que un solo pg-licht responde por una base de datos o por cientos. Las conexiones se nombran una vez, en un solo archivo, y se abren solo cuando una llamada las necesita.

Un solo pg-licht

Cien bases de datos, una sola entrada en tu cliente MCP

  • Un proceso, un archivo de conexiones, credenciales guardadas en los archivos .pgpass y de servicio propios de libpq.
  • Una lista de herramientas en la sesión del agente. Su tamaño es el mismo con 1, 150 o 1,000 conexiones configuradas, y el arranque se mantiene por debajo de una décima de segundo.
  • Las conexiones se abren cuando una llamada las necesita; hasta 32 inactivas permanecen cálidas, y la menos recientemente usada se cierra primero.
  • Pregunta a un grupo de replicación, una instancia o cualquier grupo etiquetado en una sola llamada: hasta 32 miembros por llamada, 16 a la vez, un resultado por miembro, y cualquier miembro más allá de 32 se lista como omitido en lugar de dejarse fuera silenciosamente.

Un servidor por base de datos

Cien entradas, cien conjuntos de ajustes

  • Cien procesos que iniciar, actualizar y mantener con sesión iniciada.
  • Cien copias de las mismas herramientas, cada una bajo un nombre de servidor diferente, para que el agente las distinga.
  • Un cliente que carga definiciones de herramientas por adelantado lleva cada copia en la sesión.
  • Sin forma de hacer la misma pregunta a una réplica y a su primario en una sola llamada.

Medido con 1, 150 y 1,000 conexiones configuradas. Una advertencia que vale la pena conocer: listConnections es aproximadamente 400 bytes por conexión, así que en una flota grande pide las que quieras con pattern. listConnections y listTopology toman ambos uno, comparado contra nombres y etiquetas.

Solo lectura por construcción, no por convención

La seguridad la aplica PostgreSQL en cada llamada, no se deja al comportamiento del asistente.

Una transacción de solo lectura por llamada

Cada llamada a una base de datos se ejecuta dentro de su propia transacción READ ONLY. Una escritura, incluso una alcanzada a través de un error, falla en PostgreSQL en lugar de tener éxito. Las herramientas de pooler envían a PgBouncer solo SHOW, como el usuario de estadísticas que les des, y PgBouncer no permite nada más.

Un tiempo de espera en cada sentencia

statement_timeout se establece en la misma transacción, dos minutos por defecto y configurable por conexión, así que ninguna llamada puede retener un backend indefinidamente.

Sin SQL construido a partir de argumentos

Las consultas de catálogo están parametrizadas. Ningún esquema, tabla o término de búsqueda se concatena jamás en texto SQL.

Los planes se prueban antes de que algo se ejecute

explainQuery ejecuta una sentencia solo después de que su plan demuestre no contener escrituras, y solo dentro de un presupuesto de memoria y CPU tomado del host que declaraste.

Seguro detrás de PgBouncer

Las protecciones están limitadas a la transacción, así que se mantienen bajo agrupación de transacciones. Todo el conjunto se ejecuta a través de un PgBouncer real en cada cambio.

Honesto sobre los privilegios

checkPrivileges indica qué herramientas puede usar realmente el rol que se conecta: 59 de 73 herramientas de base de datos para un rol de inicio de sesión básico, 67 con pg_monitor.

Devuelve estructura, no tus filas

pg-licht describe estructura y estadísticas. Está construido para que un asistente pueda entender una base de datos sin ver lo que contiene, y es exacto sobre los pocos lugares donde los valores aún pueden aparecer.

Nunca

  • Escribe, altera o elimina nada.
  • Devuelve filas de una tabla. Las tres herramientas que leen una devuelven solo un sí o un no (checkKey), conteos de filas y páginas (rowScatter) o un plan con conteos de filas (explainQuery).
  • Devuelve una contraseña que posee, las opciones de una asignación de usuario o la cadena de conexión de una suscripción.
  • Devuelve un pg_qualstats constante registrado. Mantiene el literal de cada predicado que muestrea; predicateStats y suggestIndexes leen table.column = ?, y una prueba falla la compilación si un literal sembrado aparece en cualquiera de ellos.

Dónde pueden aparecer valores (14 herramientas, cada una marcada)

  • Texto de sentencias: qué sesiones se están ejecutando ahora y qué registró pg_stat_statements.
  • Estadísticas de columnas: valores más comunes y límites de histograma.
  • Planes y definiciones, que repiten los literales escritos en ellos.
  • Ajustes, como el primary_conninfo de un standby.

Cada uno de estos está limitado aún más por los propios permisos de PostgreSQL: un rol sin SELECT en una columna no obtiene ninguna de sus estadísticas, y un rol sin pg_read_all_stats solo ve sus propias sentencias. Conéctate como el rol más restringido que responda la pregunta. La lista completa está en Qué llega al llamador en el manual.

Construido para las preguntas que los operadores realmente hacen

Investigaciones guiadas

13 indicaciones guían al asistente a través de consultas lentas, contención de bloqueos, interbloqueos, inflado, espacio en disco, slots de replicación y cambios de esquema, herramienta por herramienta.

Más allá de lo que PostgreSQL mide

Donde pg_wait_sampling, pg_stat_kcache y pg_qualstats están instalados: en qué ha estado esperando el servidor, las lecturas de CPU y disco reales detrás de cada sentencia, qué predicados descartan filas y el índice que las serviría — todo unido en el query_id statementStats que informa, y cada sugerencia lista para probar con evaluateIndex sin construirla. Un contador que la plataforma del servidor no mide se informa como no disponible, con el motivo, nunca como cero.

Respuestas que puedes limitar

Los listados y búsquedas que crecen con una base de datos toman un pattern o una búsqueda más restringida, y las respuestas más grandes se limitan por defecto. Establece un límite en budgets.ini y una respuesta que lo supere se rechaza con los argumentos que la hacen más pequeña, en lugar de devolverse.

El pooler también

Apunta una sección a la consola de administración de PgBouncer y pregunta si los pools siguen el ritmo: clientes esperando un servidor y durante cuánto tiempo, servidores en uso contra el tamaño de cada pool, y las conexiones y ajustes detrás de ellos — leídos solo con SHOW, como el usuario de estadísticas que les des.

Consciente de la topología

Etiqueta conexiones por instancia y grupo de replicación. Los roles se observan en cada llamada, nunca se configuran, y verifyTopology verifica las etiquetas contra los servidores.

Respuestas que un cliente puede verificar

Cada herramienta declara su esquema de salida y está marcada como de solo lectura, y los clientes en MCP 2025-06-18 o posterior reciben resultados estructurados.

Probado donde importa

PostgreSQL 14 a 18, bajo AddressSanitizer, UndefinedBehaviorSanitizer, ThreadSanitizer y valgrind, a través de un pooler, con un standby, un standby en cascada, un suscriptor lógico y un cerebro dividido, compilado tanto con g++ como con clang, y en FreeBSD 14 y 15. El protocolo y ambos analizadores de configuración se someten a fuzzing en cada cambio, y clang-tidy falla la compilación ante cualquier hallazgo.

Paquetes que se instalan antes de publicarse

Cada .deb y .rpm se instala en la distribución a la que apunta y se ejecuta antes de publicar una versión, su versión se verifica contra el binario que contiene, y la fórmula de Homebrew se compila desde el código fuente en cada cambio.

Descargas que puedes verificar

Cada recurso de versión lleva procedencia de compilación firmada: gh attestation verify demuestra que un archivo fue compilado por el flujo de trabajo de versiones de este repositorio desde el commit etiquetado. Un archivo SHA256SUMS se publica junto a ellos para una verificación que no necesita GitHub CLI.

Binarios endurecidos

Los binarios de Linux son independientes de la posición, con RELRO completo, una pila no ejecutable, protección de pila y llamadas libc fortificadas — y cada binario de versión se inspecciona en busca de ellos antes de publicarse, en lugar de confiar en las banderas que se solicitaron.

Documentación generada desde el binario

La referencia y llms.txt se construyen desde la propia versión, así que no pueden describir una versión que no existe.

76 herramientas, agrupadas por lo que responden

Dos argumentos limitan una respuesta por una cadena. Los listados toman pattern, una subcadena literal de un nombre: user_ encuentra user_x, no users. Las tres herramientas de búsqueda toman web_search, búsqueda de texto completo sobre nombres, comentarios y código fuente, donde order encuentra orders pero ord no encuentra nada. Qué herramienta toma cuál.

Instalar

brew tap sqlambda/pg-licht
brew install pg-licht

claude mcp add --transport stdio pg-licht \
  -e DATABASE_URL="postgresql://user@host/db" \
  -- pg_licht_mcp

# ~/.config/pg_licht/connections.ini
[billing_prod]
service  = billing_ro
instance = pg-prod-01

[billing_replica]
service           = billing_replica_ro
replication_group = billing-ha

Los paquetes de Debian 13 y Rocky Linux 9 y los tarballs están en la página de versiones; consulta INSTALL para cada uno.