Servidor MCP de PostgreSQL
Un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona funciones de gestión de bases de datos PostgreSQL. Este servidor ayuda a analizar las configuraciones existentes de PostgreSQL, proporciona orientación para la implementación, depura problemas de la base de datos, gestiona esquemas, migra datos y supervisa el rendimiento de la base de datos.
Versión 0.2.0
Características
El servidor proporciona las siguientes herramientas:
1. Análisis y configuración de la base de datos
1.1. Analizar la base de datos ( analyze_database )
Analiza la configuración de la base de datos PostgreSQL y las métricas de rendimiento:
- Análisis de configuración
- Métricas de rendimiento
- Evaluación de seguridad
- Recomendaciones para la optimización
// Example usage
{
"analysisType": "performance" // Optional: "configuration" | "performance" | "security"
}
1.2. Obtener instrucciones de configuración ( get_setup_instructions )
Proporciona una guía paso a paso para la instalación y configuración de PostgreSQL:
- Pasos de instalación específicos de la plataforma
- Recomendaciones de configuración
- Mejores prácticas de seguridad
- Tareas posteriores a la instalación
// Example usage
{
"platform": "linux", // Required: "linux" | "macos" | "windows"
"version": "15", // Optional: PostgreSQL version
"useCase": "production" // Optional: "development" | "production"
}
1.3. Base de datos de depuración ( debug_database )
Depurar problemas comunes de PostgreSQL:
- Problemas de conexión
- Cuellos de botella en el rendimiento
- Conflictos de bloqueo
- Estado de replicación
// Example usage
{
"issue": "performance", // Required: "connection" | "performance" | "locks" | "replication"
"logLevel": "debug" // Optional: "info" | "debug" | "trace"
}
2. Gestión de esquemas
Obtenga información detallada del esquema para una base de datos o una tabla específica:
- Lista de tablas en una base de datos
- Definiciones de columnas
- Restricciones (claves primarias, claves externas, etc.)
- Índices
// Example usage
{
"tableName": "users" // Optional: specific table to get info for
}
2.2. Crear tabla ( create_table )
Crear una nueva tabla con columnas específicas:
- Definir nombres y tipos de columnas
- Establecer restricciones que acepten valores nulos
- Establecer valores predeterminados
// Example usage
{
"tableName": "users", // Required
"columns": [ // Required
{ "name": "id", "type": "SERIAL", "nullable": false },
{ "name": "username", "type": "VARCHAR(100)", "nullable": false },
{ "name": "email", "type": "VARCHAR(255)", "nullable": false },
{ "name": "created_at", "type": "TIMESTAMP", "default": "NOW()" }
]
}
2.3. Alterar tabla ( alter_table )
Modificar tablas existentes:
- Agregar nuevas columnas
- Modificar tipos de columnas o restricciones
- Columnas de caída
// Example usage
{
"tableName": "users", // Required
"operations": [ // Required
{ "type": "add", "columnName": "last_login", "dataType": "TIMESTAMP" },
{ "type": "alter", "columnName": "email", "nullable": false },
{ "type": "drop", "columnName": "temporary_field" }
]
}
2.4. Obtener enumeraciones ( get_enums )
Obtenga información sobre los tipos ENUM de PostgreSQL.
// Example usage
{
"schema": "public", // Optional
"enumName": "user_status" // Optional
}
2.5. Crear enumeración ( create_enum )
Crea un nuevo tipo ENUM en la base de datos.
// Example usage
{
"enumName": "order_status", // Required
"values": ["pending", "processing", "shipped", "delivered"], // Required
"schema": "public", // Optional
"ifNotExists": true // Optional
}
3. Migración de datos
3.1. Exportar datos de tabla ( export_table_data )
Exportar datos de la tabla a formato JSON o CSV:
- Filtrar datos con la cláusula WHERE
- Limitar el número de filas
- Elija el formato de salida
// Example usage
{
"tableName": "users", // Required
"outputPath": "./exports/users.json", // Required
"where": "created_at > '2023-01-01'", // Optional
"limit": 1000, // Optional
"format": "json" // Optional: "json" | "csv"
}
3.2. Importar datos de tabla ( import_table_data )
Importar datos desde archivos JSON o CSV:
- Opcionalmente, truncar la tabla antes de importarla
- Soporte para diferentes formatos
- Delimitadores CSV personalizados
// Example usage
{
"tableName": "users", // Required
"inputPath": "./imports/users.json", // Required
"truncateFirst": false, // Optional
"format": "json", // Optional: "json" | "csv"
"delimiter": "," // Optional: for CSV files
}
3.3. Copiar entre bases de datos ( copy_between_databases )
Copiar datos entre dos bases de datos PostgreSQL:
- Filtrar datos con la cláusula WHERE
- Truncar opcionalmente la tabla de destino
// Example usage
{
"sourceConnectionString": "postgresql://user:password@localhost:5432/source_db", // Required
"targetConnectionString": "postgresql://user:password@localhost:5432/target_db", // Required
"tableName": "users", // Required
"where": "active = true", // Optional
"truncateTarget": false // Optional
}
4. Monitoreo
4.1. Base de datos de monitor ( monitor_database )
Monitoreo en tiempo real de la base de datos PostgreSQL:
- Métricas de base de datos (conexiones, tasa de aciertos de caché, etc.)
- Métricas de tabla (tamaño, número de filas, tuplas muertas)
- Información de consulta activa
- Información de bloqueo
- Estado de replicación
- Alertas configurables
// Example usage
{
"includeTables": true, // Optional
"includeQueries": true, // Optional
"includeLocks": true, // Optional
"includeReplication": false, // Optional
"alertThresholds": { // Optional
"connectionPercentage": 80,
"longRunningQuerySeconds": 30,
"cacheHitRatio": 0.95,
"deadTuplesPercentage": 10,
"vacuumAge": 7
}
}
5. Funciones
5.1. Obtener funciones ( get_functions )
Obtenga información sobre las funciones de PostgreSQL.
// Example usage
{
"functionName": "calculate_total", // Optional
"schema": "public" // Optional
}
5.2. Crear función ( create_function )
Crear o reemplazar una función PostgreSQL.
// Example usage
{
"functionName": "get_user_count", // Required
"parameters": "", // Required (empty if no params)
"returnType": "integer", // Required
"functionBody": "SELECT count(*) FROM users;", // Required
"language": "sql", // Optional
"volatility": "STABLE", // Optional
"schema": "public", // Optional
"security": "INVOKER", // Optional
"replace": true // Optional
}
5.3. Función de eliminación ( drop_function )
Eliminar una función PostgreSQL.
// Example usage
{
"functionName": "old_function", // Required
"parameters": "integer", // Optional: required for overloaded functions
"schema": "public", // Optional
"ifExists": true, // Optional
"cascade": false // Optional
}
6. Seguridad a nivel de fila (RLS)
6.1. Habilitar RLS ( enable_rls )
Habilitar seguridad a nivel de fila en una tabla.
// Example usage
{
"tableName": "sensitive_data", // Required
"schema": "secure" // Optional
}
6.2. Deshabilitar RLS ( disable_rls )
Deshabilitar la seguridad a nivel de fila en una tabla.
// Example usage
{
"tableName": "sensitive_data", // Required
"schema": "secure" // Optional
}
6.3. Crear una política RLS ( create_rls_policy )
Crear una política de seguridad a nivel de fila.
// Example usage
{
"tableName": "documents", // Required
"policyName": "user_can_see_own_docs", // Required
"using": "owner_id = current_user_id()", // Required
"check": "owner_id = current_user_id()", // Optional
"schema": "public", // Optional
"command": "SELECT", // Optional
"role": "app_user", // Optional
"replace": false // Optional
}
6.4. Editar la política RLS ( edit_rls_policy )
Editar una política de seguridad de nivel de fila existente.
// Example usage
{
"tableName": "documents", // Required
"policyName": "user_can_see_own_docs", // Required
"schema": "public", // Optional
"roles": ["app_user", "admin_user"], // Optional: New roles (empty or omit to keep existing/use default)
"using": "owner_id = current_user_id() OR is_admin(current_user_id())", // Optional: New USING expression
"check": "owner_id = current_user_id()" // Optional: New WITH CHECK expression
}
6.5. Política de eliminación de RLS ( drop_rls_policy )
Eliminar una política de seguridad a nivel de fila.
// Example usage
{
"tableName": "documents", // Required
"policyName": "old_policy", // Required
"schema": "public", // Optional
"ifExists": true // Optional
}
6.6. Obtener políticas de RLS ( get_rls_policies )
Obtenga políticas de seguridad a nivel de fila.
// Example usage
{
"tableName": "documents", // Optional
"schema": "public" // Optional
}
7. Desencadenantes
7.1. Obtener disparadores ( get_triggers )
Obtenga información sobre los desencadenadores de PostgreSQL.
// Example usage
{
"tableName": "audit_log", // Optional
"schema": "public" // Optional
}
7.2. Crear disparador ( create_trigger )
Crear un disparador de PostgreSQL.
// Example usage
{
"triggerName": "log_user_update", // Required
"tableName": "users", // Required
"functionName": "audit_user_change", // Required
"schema": "public", // Optional
"timing": "AFTER", // Optional
"events": ["UPDATE"], // Optional
"when": "OLD.email IS DISTINCT FROM NEW.email", // Optional
"forEach": "ROW", // Optional
"replace": false // Optional
}
7.3. Disparador de caída ( drop_trigger )
Eliminar un disparador de PostgreSQL.
// Example usage
{
"triggerName": "old_trigger", // Required
"tableName": "users", // Required
"schema": "public", // Optional
"ifExists": true, // Optional
"cascade": false // Optional
}
7.4. Establecer el estado del disparador ( set_trigger_state )
Habilitar o deshabilitar un disparador de PostgreSQL.
// Example usage
{
"triggerName": "log_user_update", // Required
"tableName": "users", // Required
"enable": false, // Required: true to enable, false to disable
"schema": "public" // Optional
}
Prerrequisitos
- Node.js >= 18.0.0
- Servidor PostgreSQL (para operaciones de base de datos de destino)
- Acceso de red a instancias de PostgreSQL de destino
Instalación
Para instalar postgresql-mcp-server para Claude Desktop automáticamente a través de Smithery :
npx -y @smithery/cli install @HenkDz/postgresql-mcp-server --client claude
Instalación manual
- Clonar el repositorio
- Instalar dependencias:
- Construir el servidor:
- Agregar al archivo de configuración de MCP (por ejemplo, en la configuración de su IDE o en una configuración global de MCP):Hay algunas formas de configurar la cadena de conexión para el servidor, con el siguiente orden de precedencia:
- Argumento específico de la herramienta : si se proporciona una
connectionString directamente en los argumentos al llamar a una herramienta específica, ese valor se utilizará para esa llamada. - Argumento CLI : puede proporcionar una cadena de conexión predeterminada al iniciar el servidor utilizando el argumento
-cs o --connection-string . - Variable de entorno : si no se proporciona ninguna de las anteriores, el servidor buscará una variable de entorno
POSTGRES_CONNECTION_STRING .
Si no se encuentra ninguna cadena de conexión a través de ninguno de estos métodos, las herramientas que requieren una conexión a la base de datos fallarán.
Ejemplo de uso del argumento CLI en la configuración de MCP:
{
"mcpServers": {
"postgresql-mcp": {
"command": "node",
"args": [
"/path/to/postgresql-mcp-server/build/index.js",
"--connection-string",
"postgresql://username:password@server:port/dbname"
// Optionally, add "--tools-config", "/path/to/your/mcp-tools.json"
],
"disabled": false,
"alwaysAllow": []
// Note: 'env' block for POSTGRES_CONNECTION_STRING can still be used as a fallback
// if --connection-string is not provided in args.
}
}
}
Ejemplo que utiliza una variable de entorno (si no se utiliza el argumento CLI):
{
"mcpServers": {
"postgresql-mcp": {
"command": "node",
"args": [
"/path/to/postgresql-mcp-server/build/index.js"
// Optionally, add "--tools-config", "/path/to/your/mcp-tools.json"
],
"disabled": false,
"alwaysAllow": [],
"env": {
"POSTGRES_CONNECTION_STRING": "postgresql://username:password@server:port/dbname"
}
}
}
}
El uso del argumento CLI --connection-string o la variable de entorno POSTGRES_CONNECTION_STRING hace que el argumento connectionString sea opcional para la mayoría de las llamadas de herramientas.
Configuración de herramientas
El servidor admite el filtrado de qué herramientas están habilitadas a través de un archivo de configuración JSON externo.
- Opción CLI : utilice
-tc <path> o --tools-config <path> para especificar la ruta a su archivo de configuración de herramientas. - Formato de archivo : el archivo JSON debe contener un objeto con una clave
enabledTools , que contiene una matriz de cadenas de nombres de herramientas.Ejemplo mcp-tools.json :{
"enabledTools": [
"get_schema_info",
"analyze_database",
"export_table_data"
]
}
- Comportamiento :
- Si se proporciona el archivo de configuración y es válido, solo se habilitarán las herramientas enumeradas.
- Si no se proporciona el archivo, no es válido o no se puede leer, todas las herramientas se habilitarán de forma predeterminada.
- El servidor registrará qué herramientas están habilitadas en función de esta configuración.
Desarrollo
npm run dev : inicia el servidor de desarrollo con recarga activanpm run lint - Ejecutar ESLintnpm test - Ejecutar pruebas (si está configurado)
Consideraciones de seguridad
- Seguridad de la conexión
- El servidor determina la cadena de conexión a la base de datos según la siguiente precedencia:
connectionString proporcionada directamente en los argumentos de una herramienta.--connection-string Argumento CLI utilizado al iniciar el servidor.- Variable de entorno
POSTGRES_CONNECTION_STRING .
- Asegúrese de que las cadenas de conexión (especialmente aquellas con credenciales) se administren de forma segura.
- Utiliza agrupación de conexiones a través de
pg (anteriormente @vercel/postgres ). - Valida cadenas de conexión.
- Admite conexiones SSL/TLS (configuración mediante cadena de conexión).
- Seguridad de consultas
- Ejecuta operaciones predefinidas; evita la ejecución arbitraria de SQL siempre que sea posible.
- Utiliza consultas parametrizadas cuando sea aplicable para evitar la inyección de SQL.
- Registra operaciones para auditoría.
- Autenticación
- Se basa en los mecanismos de autenticación de PostgreSQL a través de la cadena de conexión.
- Administre de forma segura las credenciales de su base de datos. Si es posible, no las codifique en las solicitudes de cliente; utilice preferentemente la opción CLI
--connection-string o la variable de entorno POSTGRES_CONNECTION_STRING al configurar el servidor.
Mejores prácticas
- Configure la cadena de conexión de base de datos predeterminada de forma segura utilizando la opción CLI
--connection-string o la variable de entorno POSTGRES_CONNECTION_STRING . - Si una herramienta necesita conectarse a una base de datos diferente a la predeterminada, proporcione la
connectionString directamente en los argumentos de esa herramienta. - Utilice siempre cadenas de conexión seguras con credenciales adecuadas, preferiblemente configuradas a través de la variable de entorno
POSTGRES_CONNECTION_STRING . - Siga las recomendaciones de seguridad de producción para entornos sensibles.
- Supervise y analice periódicamente el rendimiento de la base de datos utilizando la herramienta
monitor_database . - Mantenga la versión de PostgreSQL actualizada.
- Implementar estrategias de backup adecuadas de forma independiente.
- Utilice la agrupación de conexiones para una mejor gestión de recursos (gestionada internamente).
- Implementar el manejo y registro de errores adecuados.
- Auditorías y actualizaciones de seguridad periódicas.
Manejo de errores
El servidor implementa el manejo de errores para:
- Fallos de conexión
- Errores de consulta
- Entradas no válidas
- Problemas de permisos
Los errores se devuelven en el formato de error MCP estándar.
Contribuyendo
- Bifurcar el repositorio
- Crear una rama de características
- Confirme sus cambios
- Empujar hacia la rama
- Crear una solicitud de extracción
Licencia
Este proyecto está licenciado bajo la licencia AGPLv3: consulte el archivo de LICENCIA para obtener más detalles.