Servidor MCP de acceso completo de PostgreSQL

Un potente servidor de Protocolo de Contexto de Modelo (MPP) que proporciona acceso completo de lectura y escritura a bases de datos PostgreSQL. A diferencia del servidor MCP oficial de PostgreSQL de solo lectura, esta implementación mejorada permite a los Modelos de Lenguaje Grandes (LLM) consultar y modificar el contenido de la base de datos con una gestión de transacciones y controles de seguridad adecuados.

Tabla de contenido

• Características
  • Acceso completo de lectura y escritura
  • Información de esquema enriquecida
  • Controles de seguridad avanzados
• Herramientas
  • ejecutar_consulta
  • ejecutar_dml_ddl_dcl_tcl
  • ejecutar_confirmación
  • ejecutar_rollback
  • listas_de_tablas
  • describe_tabla
• Recursos
• Uso con Claude Desktop
  • Integración de escritorio de Claude
  • Importante: usar "Permitir una vez" por seguridad
• Variables de entorno
• Uso del acceso completo a la base de datos con Claude
• Consideraciones de seguridad
  • Permisos de usuario de la base de datos
  • Mejores prácticas para un uso seguro
• Estibador
• Licencia
• Comparación con el servidor MCP oficial de PostgreSQL

🌟 Características

Acceso completo de lectura y escritura

• Ejecutar de forma segura operaciones DML (INSERTAR, ACTUALIZAR, ELIMINAR)
• Crear, modificar y administrar objetos de base de datos con DDL
• Gestión de transacciones con confirmación explícita
• Tiempos de espera de seguridad y protección de reversión automática

Información de esquema enriquecida

• Metadatos de columna detallados (tipos de datos, descripciones, longitud máxima, nulabilidad)
• Identificación de clave principal
• Relaciones de clave externa
• Información de índice con indicadores de tipo y unicidad
• Estimaciones del recuento de filas de la tabla
• Descripciones de tablas y columnas (cuando estén disponibles)

Controles de seguridad avanzados

• Clasificación de consultas SQL (DQL, DML, DDL, DCL, TCL)
• Ejecución de solo lectura forzada para consultas seguras
• Todas las operaciones se ejecutan en transacciones aisladas
• Monitoreo automático del tiempo de espera de las transacciones
• Límites de seguridad configurables
• Proceso de confirmación de transacción de dos pasos con confirmación explícita del usuario

🔧 Herramientas

• ejecutar_consulta
  • Ejecutar consultas SQL de solo lectura (instrucciones SELECT)
  • Entrada: sql (cadena): La consulta SQL a ejecutar
  • Todas las consultas se ejecutan dentro de una transacción de SOLO LECTURA
  • Los resultados incluyen métricas de tiempo de ejecución e información de campo.
• ejecutar_dml_ddl_dcl_tcl
  • Ejecutar operaciones de modificación de datos (INSERTAR, ACTUALIZAR, ELIMINAR) o cambios de esquema (CREAR, ALTERAR, ELIMINAR)
  • Entrada: sql (cadena): La declaración SQL a ejecutar
  • Envuelto automáticamente en una transacción con tiempo de espera configurable
  • Devuelve un ID de transacción para confirmación explícita
  • Característica de seguridad importante : la conversación finalizará después de la ejecución, lo que permitirá al usuario revisar los resultados antes de decidir confirmar o revertir.
• ejecutar_confirmación
  • Confirmar explícitamente una transacción por su ID
  • Entrada: transaction_id (cadena): ID de la transacción a confirmar
  • Maneja de forma segura la limpieza después de confirmar o revertir
  • Aplica permanentemente los cambios a la base de datos
• ejecutar_rollback
  • Revertir explícitamente una transacción por su ID
  • Entrada: transaction_id (cadena): ID de la transacción a revertir
  • Descarta de forma segura todos los cambios y limpia los recursos
  • Útil para revisar cambios y decidir no aplicarlos.
• listas_de_tablas
  • Obtenga una lista completa de todas las tablas de la base de datos
  • Incluye recuento de columnas y descripciones de tablas.
  • No se requieren parámetros de entrada
• describe_tabla
  • Obtenga información detallada sobre una estructura de tabla específica
  • Entrada: table_name (cadena): Nombre de la tabla a describir
  • Devuelve información completa del esquema, incluidas claves principales, claves externas, índices y detalles de columnas.

📊 Recursos

El servidor proporciona información de esquema mejorada para las tablas de base de datos:

• Esquemas de tabla ( postgres://<host>/<table>/schema )
  • Información detallada del esquema JSON para cada tabla
  • Incluye metadatos de columna completos, claves principales y restricciones.
  • Descubierto automáticamente a partir de metadatos de la base de datos

🚀 Uso con Claude Desktop

Integración de escritorio de Claude

Para utilizar este servidor con Claude Desktop, siga estos pasos:

1. Primero, asegúrese de tener Node.js instalado en su sistema
2. Instala el paquete usando npx o agrégalo a tu proyecto
3. Configure Claude Desktop editando claude_desktop_config.json (normalmente se encuentra en ~/Library/Application Support/Claude/ en macOS):

4. Reemplace la cadena de conexión de la base de datos con los detalles reales de su conexión PostgreSQL
5. Reiniciar Claude Desktop por completo

Importante: usar "Permitir una vez" por seguridad

Cuando Claude intente realizar cambios en su base de datos, Claude Desktop le solicitará su aprobación:

¡Siempre revise cuidadosamente los cambios de SQL antes de aprobarlos!

Mejores prácticas de seguridad:

• Haga clic siempre en "Permitir una vez" (no "Permitir siempre") para las operaciones de confirmación
• Revise la transacción SQL cuidadosamente antes de aprobarla
• Considere utilizar un usuario de base de datos con permisos limitados
• Utilice una base de datos de prueba si es posible cuando pruebe este servidor por primera vez

Este enfoque de "Permitir una vez" le brinda control total para evitar cambios no deseados en su base de datos y, al mismo tiempo, permite que Claude lo ayude con las tareas de administración de datos cuando sea necesario.

⚙️ Variables de entorno

Puede personalizar el comportamiento del servidor con variables de entorno en su configuración de Claude Desktop:

Variables ambientales clave:

• TRANSACTION_TIMEOUT_MS : Tiempo de espera de la transacción en milisegundos (valor predeterminado: 15000)
  • Aumente esto si sus transacciones necesitan más tiempo
  • Las transacciones que excedan este tiempo se revertirán automáticamente por seguridad.
• MAX_CONCURRENT_TRANSACTIONS : Máximo de transacciones simultáneas (predeterminado: 10)
  • Reduzca este número para un funcionamiento más conservador.
  • Los valores más altos permiten más operaciones de escritura simultáneas
• ENABLE_TRANSACTION_MONITOR : Habilitar o deshabilitar el monitor de transacciones ("verdadero" o "falso", predeterminado: "verdadero")
  • Monitorea y revierte automáticamente las transacciones abandonadas
  • Rara vez necesita ser deshabilitado
• PG_STATEMENT_TIMEOUT_MS : Tiempo de espera de ejecución de la consulta SQL en ms (valor predeterminado: 30000)
  • Limita el tiempo durante el cual se puede ejecutar una sola declaración SQL
  • Característica de seguridad importante para evitar consultas descontroladas
• PG_MAX_CONNECTIONS : Máximo de conexiones PostgreSQL (predeterminado: 20)
  • Es importante mantenerse dentro de los límites de conexión de su base de datos
• MONITOR_INTERVAL_MS : Con qué frecuencia verificar transacciones bloqueadas (valor predeterminado: 5000)
  • Generalmente no necesita ajuste

🔄 Cómo usar el acceso completo a la base de datos con Claude

Este servidor permite a Claude leer y escribir en su base de datos PostgreSQL con su aprobación. A continuación, se muestran algunos ejemplos de flujos de conversación:

Ejemplo: crear una nueva tabla y agregar datos

Tú: "Necesito una nueva tabla de productos con columnas para id, nombre, precio e inventario"

Claude: Analiza tu base de datos y crea una consulta.

Claude Desktop le solicitará que apruebe esta operación

Tú: Revisa y haz clic en "Permitir una vez"

Claude: "He creado la tabla de productos. ¿Quieres que añada algunos datos de muestra?"

Tú: "Sí, por favor, añade 5 productos de muestra"

Claude: Crea declaraciones INSERT y solicita aprobación. Usted revisa y aprueba con "Permitir una vez".

Ejemplo: Análisis de datos con consultas seguras

Tú: "¿Cuáles son mis 3 productos favoritos por precio?"

Claude: ejecuta una consulta de solo lectura automáticamente. Te muestra los resultados.

Flujo de trabajo de seguridad

La característica de seguridad clave es el enfoque de dos pasos para cualquier operación que modifique su base de datos:

1. Claude analiza su solicitud y prepara SQL
2. Para operaciones de solo lectura (SELECT), Claude se ejecuta automáticamente
3. Para operaciones de escritura (INSERTAR, ACTUALIZAR, ELIMINAR, CREAR, etc.):
   • Claude ejecuta el SQL en una transacción y finaliza la conversación.
   • Revisa los resultados
   • En una nueva conversación, responde con "Sí" para confirmar o "No" para revertir.
   • Claude Desktop te muestra exactamente qué se cambiará y te pide permiso
   • Haga clic en "Permitir una vez" para permitir la operación específica
   • Claude ejecuta la operación y devuelve resultados.

Esto le brinda múltiples oportunidades para verificar los cambios antes de que se apliquen permanentemente a la base de datos.

⚠️ Consideraciones de seguridad

Al conectar a Claude a su base de datos con acceso de escritura:

Permisos de usuario de la base de datos

IMPORTANTE: Cree un usuario de base de datos dedicado con los permisos adecuados:

Mejores prácticas para un uso seguro

1. Utilice siempre "Permitir una vez" para revisar cada operación de escritura
   • Nunca seleccione "Permitir siempre" para modificaciones de la base de datos
   • Tómese el tiempo para revisar el SQL cuidadosamente
2. Conéctese a una base de datos de prueba cuando explore esta herramienta por primera vez
   • Considere usar una copia/copia de seguridad de la base de datos para las pruebas iniciales
3. Limite los permisos de usuario de la base de datos únicamente a lo necesario
   • Evite utilizar una cuenta de superusuario o administrador
   • Otorgar permisos específicos para tablas cuando sea posible
4. Implementar copias de seguridad de la base de datos antes de un uso extensivo
5. Nunca comparta datos confidenciales que no deberían estar expuestos a los LLM
6. Verificar todas las operaciones SQL antes de aprobarlas
   • Comprobar los nombres de las tablas
   • Verificar los nombres de las columnas y los datos
   • Confirmar que las cláusulas WHERE sean apropiadas
   • Busque un manejo adecuado de las transacciones

Estibador

El servidor se puede ejecutar fácilmente en un contenedor Docker:

Para Docker en macOS, use host.docker.internal para conectarse a la red del host:

📄 Licencia

Este servidor MCP tiene licencia MIT.

💡 Comparación con el servidor MCP oficial de PostgreSQL

Autor

Creado por Syahiid Nur Kamil ( @syahiidkamil )

Copyright © 2024 Syahiid Nur Kamil. Todos los derechos reservados.