PostgreSQL MCP Server

Servidor MCP de PostgreSQL

Un servidor del Protocolo de Contexto de Modelo (MCP) que proporciona capacidades integrales de gestión de bases de datos PostgreSQL para asistentes de IA.

🚀 Novedades: Este servidor ha sido completamente rediseñado de 46 herramientas individuales a 18 herramientas inteligentes mediante consolidación (34→8 meta-herramientas) y mejora (+4 nuevas herramientas), proporcionando un mejor descubrimiento para IA y añadiendo potentes capacidades de manipulación de datos y gestión de comentarios.

Cambios importantes en 2.0.0

La versión 2.0.0 introduce límites de seguridad que cambian intencionalmente el comportamiento predeterminado respecto a la línea 1.x:

• El servidor se inicia en modo readonly. Las mutaciones, DDL, administración de roles, importación/exportación de archivos y SQL arbitrario requieren --security-mode write, --security-mode admin o --security-mode unsafe según corresponda.
• Las operaciones destructivas como eliminaciones, restablecimientos, concesiones amplias de roles y SQL arbitrario requieren --allow-destructive.
• Los argumentos connectionString, sourceConnectionString y targetConnectionString por herramienta están deshabilitados de forma predeterminada. Use --connection-string o POSTGRES_CONNECTION_STRING a nivel de servidor, o active explícitamente con --allow-tool-connection-string.
• Las cláusulas where de cadena heredadas se rechazan para filtros de mutación, índice, exportación y copia. Use predicados where estructurados, o rawWhere solo con --security-mode unsafe --allow-destructive.
• Las llamadas pg_execute_sql de múltiples declaraciones deben usar transactional: true, expectRows: false y sin enlace parameters.
• Los esquemas de herramientas rechazan campos desconocidos, por lo que las entradas mal escritas o no intencionadas fallan antes de la resolución de la conexión.
• Los identificadores de usuario y destino están restringidos a identificadores simples y seguros de PostgreSQL.

Para la línea de parches de seguridad sin cambios importantes, use @henkey/postgres-mcp-server@1.0.7.

Inicio rápido

Requisitos previos

• Node.js ≥18.0.0
• Acceso a un servidor PostgreSQL
• (Opcional) Un cliente MCP como Cursor o Claude para integración con IA

Opción 1: npm (Recomendado)

# Install globally
npm install -g @henkey/postgres-mcp-server

# Or run directly with npx (no installation)
# Use env var for connection string (optional)
export POSTGRES_CONNECTION_STRING="postgresql://user:pass@localhost:5432/db"
npx @henkey/postgres-mcp-server
# Or pass directly:
npx @henkey/postgres-mcp-server --connection-string "postgresql://user:pass@localhost:5432/db"

Verificar la instalación

npx @henkey/postgres-mcp-server --help

Agregue a la configuración de su cliente MCP:

{
  "mcpServers": {
    "postgresql-mcp": {
      "command": "npx",
      "args": [
        "@henkey/postgres-mcp-server",
        "--connection-string", "postgresql://user:password@host:port/database"
      ]
    }
  }
}

Opción 2: Instalar mediante Smithery

npx -y @smithery/cli install @HenkDz/postgresql-mcp-server --client claude

Opción 3: Docker (Recomendado para producción)

# Build the Docker image
docker build -t postgres-mcp-server .

# Run with environment variable
docker run -i --rm \
  -e POSTGRES_CONNECTION_STRING="postgresql://user:password@host:port/database" \
  postgres-mcp-server

Agregue a la configuración de su cliente MCP:

{
  "mcpServers": {
    "postgresql-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "henkey/postgres-mcp:latest",
        "-e",
        "POSTGRES_CONNECTION_STRING"
      ],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://user:password@host:port/database"
      }
    }
  }
}

Opción 4: Instalación manual (Desarrollo)

git clone <repository-url>
cd postgresql-mcp-server
npm install
npm run build

Agregue a la configuración de su cliente MCP:

{
  "mcpServers": {
    "postgresql-mcp": {
      "command": "node",
      "args": [
        "/path/to/postgresql-mcp-server/build/index.js",
        "--connection-string", "postgresql://user:password@host:port/database"
      ]
    }
  }
}

Modos de seguridad

El servidor ahora se inicia en modo readonly de forma predeterminada. Las herramientas aún pueden aparecer en la lista para el descubrimiento MCP, pero cada llamada se clasifica y verifica antes de llegar a la base de datos.

Modo	Permite	Bloquea de forma predeterminada
readonly	inspección de esquemas, análisis, monitoreo, herramientas de consulta tipo SELECT	mutaciones, DDL, cambios de roles, importación/exportación de archivos, SQL arbitrario
write	operaciones de solo lectura más mutaciones de datos	DDL, cambios de roles, importación/exportación de archivos, SQL arbitrario
admin	operaciones de escritura más herramientas de esquema, índice, función, disparador, RLS, rol y archivos	SQL arbitrario
unsafe	todas las categorías de herramientas, incluido SQL arbitrario	operaciones destructivas a menos que se permitan explícitamente

Las operaciones destructivas como eliminaciones, restablecimientos y SQL arbitrario también requieren aceptación explícita:

# Default: readonly, no per-tool connection strings
npx @henkey/postgres-mcp-server --connection-string "postgresql://readonly_user:pass@host:5432/db"

# Enable DML mutations, but still block DDL/admin/arbitrary SQL
npx @henkey/postgres-mcp-server --security-mode write --connection-string "postgresql://app_writer:pass@host:5432/db"

# Enable admin tools and destructive operations
npx @henkey/postgres-mcp-server --security-mode admin --allow-destructive --connection-string "postgresql://admin_user:pass@host:5432/db"

# Enable arbitrary SQL only for trusted local/admin use
npx @henkey/postgres-mcp-server --security-mode unsafe --allow-destructive --connection-string "postgresql://admin_user:pass@host:5432/db"

Los argumentos connectionString, sourceConnectionString y targetConnectionString por herramienta están deshabilitados de forma predeterminada. Prefiera una cadena de conexión fija a nivel de servidor con un rol de PostgreSQL de privilegios mínimos. Solo para desarrollo, habilite cadenas de conexión por herramienta con --allow-tool-connection-string o POSTGRES_MCP_ALLOW_TOOL_CONNECTION_STRING=true. Los valores explícitos por herramienta, CLI y POSTGRES_CONNECTION_STRING deben ser cadenas no vacías. Las cadenas de conexión en blanco de mayor prioridad fallan la validación en lugar de recurrir a fuentes de menor prioridad.

Opcionalmente, restrinja todas las cadenas de conexión a nivel de servidor y por herramienta a una lista de permitidos con --allowed-connection-target, allowedConnectionTargets o POSTGRES_MCP_ALLOWED_CONNECTION_TARGETS. Los patrones de destino usan [user@]host[:port][/database]; los campos omitidos no están restringidos y * solo se permite como comodín de campo completo, por ejemplo readonly@db.internal:5432/app o *@localhost:*/dev.

Para concesiones de implementación, consulte Plantillas de roles de PostgreSQL. Las plantillas dividen las credenciales de solo lectura, escritor, administrador de esquemas y administrador de roles para que el rol de PostgreSQL permanezca alineado con el securityMode seleccionado.

La configuración de seguridad también se puede colocar en el archivo de configuración de herramientas:

{
  "securityMode": "readonly",
  "allowDestructive": false,
  "allowToolConnectionString": false,
  "workspaceDir": "/path/to/mcp-workspace",
  "auditFile": "/path/to/postgres-mcp-audit.jsonl",
  "maxConnections": 20,
  "idleTimeoutMillis": 30000,
  "connectionTimeoutMillis": 2000,
  "maxFileBytes": 10485760,
  "statementTimeoutMs": 30000,
  "queryTimeoutMs": 45000,
  "lockTimeoutMs": 10000,
  "idleInTransactionSessionTimeoutMs": 60000,
  "allowedConnectionTargets": [
    "readonly@db.internal:5432/app"
  ],
  "enabledTools": [
    "pg_analyze_database",
    "pg_manage_schema",
    "pg_execute_query"
  ]
}

La precedencia de configuración en tiempo de ejecución es: opciones de CLI, luego el archivo de configuración de herramientas, luego variables de entorno. Los valores explícitos de false en la configuración de herramientas anulan las variables de entorno habilitadoras como POSTGRES_MCP_ALLOW_DESTRUCTIVE=true.

Si se proporciona una ruta de configuración de herramientas, el servidor la trata como obligatoria: entradas ilegibles, malformadas, que no sean objetos, con tipos incorrectos, claves desconocidas, securityMode inválidos o entradas enabledTools desconocidas detienen el inicio en lugar de recurrir a todas las herramientas disponibles.

Opciones de CLI:

• --version
• --connection-string
• --tools-config
• --security-mode
• --allow-destructive
• --allow-tool-connection-string
• --workspace-dir
• --audit-file
• --max-connections
• --idle-timeout-ms
• --connection-timeout-ms
• --max-file-bytes
• --statement-timeout-ms
• --query-timeout-ms
• --lock-timeout-ms
• --idle-in-transaction-session-timeout-ms
• --allowed-connection-target

Variables de entorno:

• POSTGRES_TOOLS_CONFIG=/path/to/tools.json
• POSTGRES_MCP_SECURITY_MODE=readonly|write|admin|unsafe
• POSTGRES_MCP_ALLOW_DESTRUCTIVE=true
• POSTGRES_MCP_ALLOW_TOOL_CONNECTION_STRING=true
• POSTGRES_MCP_WORKSPACE_DIR=/path/to/mcp-workspace
• POSTGRES_MCP_AUDIT_FILE=/path/to/postgres-mcp-audit.jsonl
• POSTGRES_MCP_MAX_CONNECTIONS=20
• POSTGRES_MCP_IDLE_TIMEOUT_MS=30000
• POSTGRES_MCP_CONNECTION_TIMEOUT_MS=2000
• POSTGRES_MCP_MAX_FILE_BYTES=10485760
• POSTGRES_MCP_STATEMENT_TIMEOUT_MS=60000
• POSTGRES_MCP_QUERY_TIMEOUT_MS=65000
• POSTGRES_MCP_LOCK_TIMEOUT_MS=10000
• POSTGRES_MCP_IDLE_IN_TRANSACTION_SESSION_TIMEOUT_MS=60000
• POSTGRES_MCP_ALLOWED_CONNECTION_TARGETS=readonly@db.internal:5432/app,*@localhost:*/dev
• POSTGRES_MCP_DEBUG_SQL=true para optar por el rastreo detallado de SQL pg-monitor. Esto puede registrar SQL sin procesar y valores de enlace, así que déjelo deshabilitado a menos que esté depurando una base de datos local de confianza.

Las banderas booleanas de entorno deben ser exactamente true o false cuando se establecen. Los ajustes numéricos de recursos desde CLI, configuración de herramientas o variables de entorno deben ser enteros positivos. Los valores predeterminados en tiempo de ejecución usan un grupo de 20 conexiones, un tiempo de espera de inactividad del grupo de 30000 ms, un tiempo de espera de conexión de 2000 ms, un statement_timeout de PostgreSQL de 60000 ms, un tiempo de espera de consulta de node-postgres de 65000 ms, un lock_timeout de PostgreSQL de 10000 ms y un idle_in_transaction_session_timeout de PostgreSQL de 60000 ms. Los ajustes de grupo y tiempo de espera se pueden aumentar o reducir con --max-connections, --idle-timeout-ms, --connection-timeout-ms, --statement-timeout-ms, --query-timeout-ms, --lock-timeout-ms, --idle-in-transaction-session-timeout-ms, maxConnections, idleTimeoutMillis, connectionTimeoutMillis, statementTimeoutMs, queryTimeoutMs, lockTimeoutMs, idleInTransactionSessionTimeoutMs, POSTGRES_MCP_MAX_CONNECTIONS, POSTGRES_MCP_IDLE_TIMEOUT_MS, POSTGRES_MCP_CONNECTION_TIMEOUT_MS, POSTGRES_MCP_STATEMENT_TIMEOUT_MS, POSTGRES_MCP_QUERY_TIMEOUT_MS, POSTGRES_MCP_LOCK_TIMEOUT_MS o POSTGRES_MCP_IDLE_IN_TRANSACTION_SESSION_TIMEOUT_MS. Los valores explícitos de cadena de conexión, workspaceDir, auditFile, --workspace-dir y --audit-file deben ser cadenas no vacías. Las listas de permitidos de destino de conexión se aplican antes de la ejecución de la herramienta para cadenas de conexión por herramienta y durante la resolución de conexión para fuentes a nivel de servidor. Cuando se configura una lista de permitidos, las cadenas de conexión deben ser URL de PostgreSQL o cadenas de estilo de palabras clave con un host o hostaddr explícito.

Los filtros de mutación, índice, exportación y copia deben usar predicados where estructurados. Las cláusulas where de cadena heredadas se rechazan; la vía de escape explícita rawWhere se trata como SQL arbitrario y requiere --security-mode unsafe --allow-destructive.

Las herramientas EXPLAIN solo aceptan una declaración de solo lectura y se ejecutan dentro de una transacción de solo lectura. analyze: true aún requiere modo inseguro porque PostgreSQL ejecuta la consulta proporcionada para recopilar estadísticas de tiempo de ejecución.

Las llamadas pg_execute_sql de múltiples declaraciones deben usar transactional: true, expectRows: false y sin enlace parameters. Use una sola declaración parametrizada o CTE cuando se necesiten parámetros de enlace.

Los mensajes de error, diagnósticos y metadatos de catálogo se sanean de forma predeterminada. El texto SQL de pg_stat_statements, definiciones de funciones, predicados RLS, restricciones de verificación, definiciones de índices y valores predeterminados de columnas se redactan a menos que se devuelvan intencionalmente como datos de usuario. Las herramientas de ejecución de datos, consulta/rendimiento, esquema, índice, restricción, usuario/permiso, disparador, comentario, función, RLS, migración y diagnóstico rechazan campos de entrada desconocidos para que los parámetros mal escritos o no intencionados fallen antes de la resolución de la conexión.

Las solicitudes denegadas por límites de seguridad emiten una línea estructurada de stderr con el prefijo [MCP Audit]. Los eventos de auditoría incluyen campos saneados como toolName, reason, securityMode, risk y si estaban presentes cadenas de conexión por herramienta; no registran SQL sin procesar, cargas completas de solicitudes ni contraseñas de cadenas de conexión. Establezca POSTGRES_MCP_AUDIT_FILE, --audit-file o auditFile para agregar los mismos eventos de auditoría saneados a un archivo JSONL.

Las herramientas de archivos como exportación/importación de tablas requieren un directorio de trabajo y solo leen o escriben archivos .json y .csv dentro de él:

npx @henkey/postgres-mcp-server \
  --security-mode admin \
  --allow-destructive \
  --workspace-dir /path/to/mcp-workspace \
  --connection-string "postgresql://admin_user:pass@host:5432/db"

Qué se incluye

18 herramientas potentes organizadas en tres categorías:

• 🔄 Consolidación: 34 herramientas originales consolidadas en 8 meta-herramientas inteligentes
• 🔧 Especializadas: 6 herramientas mantenidas por separado para operaciones complejas
• 🆕 Mejora: 4 herramientas completamente nuevas (no en las 46 originales)

📊 Meta-herramientas consolidadas (8 herramientas)

• Gestión de esquemas - Tablas, columnas, ENUMs, restricciones
• Usuarios y permisos - Crear usuarios, otorgar/revocar permisos
• Rendimiento de consultas - Planes EXPLAIN, consultas lentas, estadísticas
• Gestión de índices - Crear, analizar, optimizar índices
• Funciones - Crear, modificar, gestionar funciones almacenadas
• Disparadores - Gestión de disparadores de base de datos
• Restricciones - Claves foráneas, verificaciones, restricciones únicas
• Seguridad a nivel de fila - Políticas RLS y gestión

🚀 Herramientas de mejora (4 herramientas NUEVAS)

Capacidades completamente nuevas no disponibles en las 46 herramientas originales

• Ejecutar consulta - Operaciones SELECT con soporte de conteo/existencia
• Ejecutar mutación - Operaciones INSERT/UPDATE/DELETE/UPSERT
• Ejecutar SQL - Ejecución de SQL arbitrario con soporte de transacciones
• Gestión de comentarios - Gestión integral de comentarios para todos los objetos de base de datos

🔧 Herramientas especializadas (6 herramientas)

• Análisis de base de datos - Análisis de rendimiento y configuración
• Depurar base de datos - Solucionar problemas de conexión, rendimiento, bloqueos
• Exportación de datos - Exportación de datos JSON/CSV
• Importación de datos - Importación de datos JSON/CSV
• Copiar entre bases de datos - Transferencia de datos entre bases de datos
• Monitoreo en tiempo real - Métricas y alertas de base de datos en vivo

Ejemplo de uso

// Analyze database performance
{ "analysisType": "performance", "schema": "public" }

// Create a table with constraints
{
  "operation": "create_table",
  "tableName": "users", 
  "columns": [
    { "name": "id", "type": "SERIAL PRIMARY KEY" },
    { "name": "email", "type": "VARCHAR(255) UNIQUE NOT NULL" }
  ]
}

// Query data with parameters
{
  "operation": "select",
  "query": "SELECT * FROM users WHERE created_at > $1",
  "parameters": ["2024-01-01"],
  "limit": 100
}
// Select results are always bounded: default limit 100, max 1000.

// Insert new data
{
  "operation": "insert",
  "table": "users",
  "data": {"name": "John Doe", "email": "john@example.com"},
  "returning": "*",
  "maxReturningRows": 100
}
// Mutation RETURNING output is capped in the response: default 100, max 1000.

// Find slow queries
{
  "operation": "get_slow_queries",
  "limit": 5,
  "minDuration": 100
}

// Execute a parameterized SELECT query
{
  "operation": "select",
  "query": "SELECT * FROM users WHERE id = $1",
  "parameters": [1]
}

// Perform an INSERT mutation
{
  "operation": "insert",
  "table": "products",
  "data": {"name": "New Product", "price": 99.99},
  "returning": "id",
  "maxReturningRows": 100
}

// Perform an UPDATE mutation with a structured WHERE predicate
{
  "operation": "update",
  "table": "products",
  "data": {"price": 89.99},
  "where": {"id": 123},
  "returning": ["id", "price"]
}

// Manage database object comments
{
  "operation": "set",
  "objectType": "table",
  "objectName": "users",
  "comment": "Main user account information table"
}

📚 Documentación

📋 Referencia completa del esquema de herramientas - Todos los 18 parámetros y ejemplos de herramientas en un solo lugar

Para información adicional, consulte la carpeta docs/:

• 🔐 Postura de seguridad - Aislamiento, aprobaciones, eventos de auditoría y postura de implementación
• Plantillas de roles de PostgreSQL - Roles de base de datos de privilegios mínimos para cada perfil de implementación
• 📖 Guía de uso - Patrones y ejemplos de uso endurecidos
• 🛠️ Guía de desarrollo - Configuración y lista de verificación de lanzamiento
• ⚙️ Detalles técnicos - Arquitectura de seguridad y restricciones de implementación
• 👨‍💻 Referencia para desarrolladores - Reglas de contribución para cambios de herramientas y políticas
• 📋 Índice de documentación - Descripción general completa de la documentación

Destacados de características

🔄 Logros de consolidación

✅ 34→8 meta-herramientas - Consolidación inteligente para mejor descubrimiento por IA ✅ Múltiples operaciones por herramienta - Esquemas unificados con parámetros de operación ✅ Validación inteligente de parámetros - Mensajes de error claros y seguridad de tipos

🆕 Capacidades de Datos Mejoradas

✅ Operaciones CRUD completas - INSERT/UPDATE/DELETE/UPSERT con consultas parametrizadas
✅ Consultas flexibles - SELECT con soporte de count/exists y límites de seguridad acotados ✅ Ejecución SQL arbitraria - Soporte de transacciones para operaciones complejas

🔧 Listo para Producción

✅ Conexión controlada - Argumentos de CLI o variables de entorno por defecto; cadenas de conexión por herramienta requieren opt-in ✅ Enfoque en seguridad - Modo de solo lectura por defecto, verificaciones de políticas centralizadas, predicados de mutación estructurados ✅ Arquitectura robusta - Pooling de conexiones, manejo integral de errores

Uso con Docker

El servidor PostgreSQL MCP Server es totalmente compatible con Docker y puede usarse en entornos de producción. La imagen utiliza una compilación de múltiples etapas, instala solo dependencias de producción en la etapa de ejecución y se ejecuta como el usuario no root node.

Construyendo la Imagen

# Build locally
docker build -t postgres-mcp-server .

# Or pull from Docker Hub
docker pull henkey/postgres-mcp:latest

Ejecución con Variables de Entorno

# Basic usage (using Docker Hub image)
docker run -i --rm \
  -e POSTGRES_CONNECTION_STRING="postgresql://user:password@host:port/database" \
  henkey/postgres-mcp:latest

# Or with locally built image
docker run -i --rm \
  -e POSTGRES_CONNECTION_STRING="postgresql://user:password@host:port/database" \
  postgres-mcp-server

# With tools configuration
docker run -i --rm \
  -e POSTGRES_CONNECTION_STRING="postgresql://user:password@host:port/database" \
  -e POSTGRES_TOOLS_CONFIG="/app/config/tools.json" \
  -v /path/to/config:/app/config \
  postgres-mcp-server

Ejemplo de Docker Compose

version: '3.8'
services:
  postgres-mcp:
    build: .
    environment:
      - POSTGRES_CONNECTION_STRING=postgresql://user:password@postgres:5432/database
    depends_on:
      - postgres
    stdin_open: true
    tty: true

  postgres:
    image: postgres:15
    environment:
      - POSTGRES_DB=database
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=password
    ports:
      - "5432:5432"

Configuración del Cliente MCP

Para uso con clientes MCP como Cursor o Claude Desktop:

{
  "mcpServers": {
    "postgresql-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "POSTGRES_CONNECTION_STRING",
        "henkey/postgres-mcp:latest"
      ],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://user:password@host:port/database"
      }
    }
  }
}

Requisitos Previos

• Node.js ≥ 18.0.0 (para desarrollo local)
• Docker (para despliegue en contenedores)
• Acceso al servidor PostgreSQL
• Credenciales de conexión válidas

Contribuciones

1. Haz un fork del repositorio
2. Crea una rama de características
3. Realiza tus cambios
4. Crea un Pull Request

Consulta la Guía de Desarrollo para instrucciones detalladas de configuración.

Licencia

Licencia AGPLv3 - consulta el archivo LICENSE para más detalles.