mcp-postgres-secure

MCP PostgreSQL Secure

Un servidor de Model Context Protocol para PostgreSQL con modos de acceso basados en permisos. Elige cuánto poder de base de datos recibe la IA en el momento de la instalación.

Modos de acceso

Modo	PG_ACCESS_MODE	Herramientas	SQL permitido
Solo lectura	readonly (predeterminado)	query, introspección de esquema	SELECT, WITH, EXPLAIN, SHOW, etc.
Lectura + DML	dml	anteriores + execute	DML: INSERT, UPDATE, DELETE, MERGE
Acceso completo	full	anteriores + execute (DDL)	DML + DDL: CREATE, ALTER, DROP, TRUNCATE, etc.

Defensa en profundidad:

• Clasificación de SQL a nivel de aplicación (bloquea consultas de múltiples sentencias y tipos de sentencias no permitidos)
• Sesión de PostgreSQL default_transaction_read_only = on en modo readonly
• Bloqueo de conexión mediante PG_LOCK_CONNECTION para que las credenciales no puedan intercambiarse en tiempo de ejecución al usar configuración por entorno

Combina cada modo con un rol de PostgreSQL que tenga los permisos correspondientes. El servidor aplica la intención; el usuario de la base de datos es la autoridad final.

Instalación

Desde npm

npm install mcp-postgres-secure

O ejecuta directamente:

npx mcp-postgres-secure --access-mode readonly

Desde el código fuente (fork)

git clone https://github.com/pugltd/mcp-postgres-secure.git
cd mcp-postgres-secure
npm install
npm run build

Apunta Cursor a node /absolute/path/to/mcp-postgres-secure/build/index.js.

Configuración

Todos los modos usan las mismas variables de entorno de conexión. Establece el nivel de acceso con --access-mode (CLI) o PG_ACCESS_MODE (entorno). La bandera de CLI tiene prioridad si ambas están configuradas.

Variable / bandera	Requerida	Predeterminado	Descripción
--access-mode	no	readonly	readonly, dml o full (anula el entorno)
PG_ACCESS_MODE	no	readonly	Igual que --access-mode
PG_HOST	sí	—	Host de la base de datos
PG_PORT	no	5432	Puerto de la base de datos
PG_USER	sí	—	Usuario de la base de datos
PG_PASSWORD	sí	—	Contraseña de la base de datos
PG_DATABASE	sí	—	Nombre de la base de datos
PG_LOCK_CONNECTION	no	true cuando la configuración de entorno está establecida	Desactiva connect_db en tiempo de ejecución

# CLI examples
npx mcp-postgres-secure --access-mode readonly
npx mcp-postgres-secure --access-mode=dml
node build/index.js --help

1. Solo lectura (predeterminado recomendado)

Úsalo para explorar esquemas y ejecutar análisis sin riesgo de escritura.

{
  "mcpServers": {
    "postgres-readonly": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-postgres-secure", "--access-mode", "readonly"],
      "env": {
        "PG_HOST": "localhost",
        "PG_PORT": "5432",
        "PG_USER": "mcp_readonly",
        "PG_PASSWORD": "your_password",
        "PG_DATABASE": "your_database",
        "PG_LOCK_CONNECTION": "true"
      }
    }
  }
}

2. Lectura + DML

Úsalo cuando la IA pueda insertar, actualizar o eliminar filas pero no deba cambiar el esquema.

{
  "mcpServers": {
    "postgres-dml": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-postgres-secure", "--access-mode", "dml"],
      "env": {
        "PG_HOST": "localhost",
        "PG_PORT": "5432",
        "PG_USER": "mcp_dml",
        "PG_PASSWORD": "your_password",
        "PG_DATABASE": "your_database",
        "PG_LOCK_CONNECTION": "true"
      }
    }
  }
}

3. Acceso completo (DDL)

Úsalo solo cuando se requieran cambios de esquema. Prefiere un rol de administrador dedicado con privilegios bajos, no un superusuario.

{
  "mcpServers": {
    "postgres-full": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-postgres-secure", "--access-mode", "full"],
      "env": {
        "PG_HOST": "localhost",
        "PG_PORT": "5432",
        "PG_USER": "mcp_admin",
        "PG_PASSWORD": "your_password",
        "PG_DATABASE": "your_database",
        "PG_LOCK_CONNECTION": "true"
      }
    }
  }
}

Puedes registrar múltiples entradas de MCP (por ejemplo, postgres-readonly y postgres-dml) y habilitar solo la que necesites por proyecto.

Herramientas disponibles

query

SQL de solo lectura. Admite marcadores de posición de estilo PostgreSQL ($1, $2) y de estilo MySQL (?).

use_mcp_tool({
  server_name: "postgres-readonly",
  tool_name: "query",
  arguments: {
    sql: "SELECT * FROM users WHERE id = $1",
    params: [1]
  }
});

execute (solo modos dml y completo)

SQL de mutación. En modo dml: solo INSERT, UPDATE, DELETE, MERGE. En modo full: DML y DDL.

use_mcp_tool({
  server_name: "postgres-dml",
  tool_name: "execute",
  arguments: {
    sql: "UPDATE users SET active = $1 WHERE id = $2",
    params: [true, 1]
  }
});

list_schemas, list_tables, describe_table

Introspección de esquema (todos los modos).

connect_db

Conexión opcional en tiempo de ejecución cuando PG_LOCK_CONNECTION=false y las variables de entorno no están configuradas. Deshabilitada por defecto al usar configuración basada en entorno.

Ejemplos de roles de PostgreSQL

Usuario de solo lectura:

CREATE ROLE mcp_readonly LOGIN PASSWORD '...';
GRANT CONNECT ON DATABASE your_database TO mcp_readonly;
GRANT USAGE ON SCHEMA public TO mcp_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO mcp_readonly;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO mcp_readonly;

Usuario DML (agrega permisos de escritura, sin DDL):

CREATE ROLE mcp_dml LOGIN PASSWORD '...';
-- same as above, plus:
GRANT INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO mcp_dml;

Usuario administrador (migraciones / DDL): otorga permisos solo en los esquemas que la IA deba gestionar.

Seguridad

• Consultas parametrizadas para valores proporcionados por el usuario
• Aplicación de una sola sentencia (sin lotes encadenados con ;)
• Validación del tipo de sentencia según el modo de acceso
• Transacciones de PostgreSQL de solo lectura en modo readonly
• connect_db en tiempo de ejecución deshabilitado cuando la conexión está bloqueada por entorno
• Credenciales mediante variables de entorno (no argumentos de chat)

Limitaciones: la validación se basa en palabras clave, no es un analizador SQL completo. Usa roles de base de datos con privilegios mínimos y bases de datos que no sean de producción cuando sea posible.

Manejo de errores

El servidor devuelve errores claros para:

• SQL inválido o no permitido para el modo de acceso actual
• Múltiples sentencias en una sola solicitud
• Fallos de conexión
• Parámetros faltantes
• Herramientas deshabilitadas (execute en readonly, connect_db cuando está bloqueado)

Licencia

MIT

Upstream

Bifurcado de antonorlov/mcp-postgres-server.