Servidor MCP para PostgreSQL

Servidor MCP orientado a producción para PostgreSQL, que expone operaciones de base de datos a clientes MCP (Claude Desktop, VS Code Copilot, Cursor y hosts compatibles).

Características

• Ejecución de consultas (SELECT, INSERT, UPDATE, DELETE)

• Descubrimiento de bases de datos e introspección de esquemas

• Inspección de metadatos de tablas (columnas, tipos, nulabilidad, valores por defecto, PK)

• Descubrimiento de índices y claves foráneas

• Configuración basada en entorno para despliegue seguro

Related MCP server: Azure Database for PostgreSQL MCP Server

Herramientas disponibles

Requisitos

• Node.js 18+

• Acceso a una instancia de PostgreSQL

• Conectividad de red desde el host MCP a PostgreSQL (host:puerto)

Configuración

Configure los ajustes de conexión usando variables de entorno:

Uso

Ejecutar directamente desde GitHub

npx github:ferronicardoso/mcp-postgresql

Claude Code (CLI)

claude mcp add postgresql --scope user -- npx -y github:ferronicardoso/mcp-postgresql

--scope controla dónde se almacena el registro del servidor:

Las variables de entorno se pueden pasar con banderas repetidas --env CLAVE=VALOR antes de --, por ejemplo:

Bash (Linux/macOS/WSL):

claude mcp add postgresql --scope user \
  --env PGHOST=localhost \
  --env PGPORT=5432 \
  --env PGDATABASE=postgres \
  --env PGUSER=postgres \
  --env PGPASSWORD=your-password \
  -- npx -y github:ferronicardoso/mcp-postgresql

PowerShell:

claude mcp add postgresql --scope user `
  --env PGHOST=localhost `
  --env PGPORT=5432 `
  --env PGDATABASE=postgres `
  --env PGUSER=postgres `
  --env PGPASSWORD=your-password `
  -- npx -y github:ferronicardoso/mcp-postgresql

Codex CLI

Bash (Linux/macOS/WSL):

codex mcp add postgresql \
  --env PGHOST=localhost \
  --env PGPORT=5432 \
  --env PGDATABASE=postgres \
  --env PGUSER=postgres \
  --env PGPASSWORD=your-password \
  npx -- -y github:ferronicardoso/mcp-postgresql

PowerShell:

codex mcp add postgresql `
  --env PGHOST=localhost `
  --env PGPORT=5432 `
  --env PGDATABASE=postgres `
  --env PGUSER=postgres `
  --env PGPASSWORD=your-password `
  npx -- -y github:ferronicardoso/mcp-postgresql

Esto registra el servidor en ~/.codex/config.toml. Para eliminarlo, ejecuta codex mcp remove postgresql.

Configuración de Claude Desktop

%APPDATA%\\Claude\\claude_desktop_config.json:

{
  "mcpServers": {
    "postgresql": {
      "command": "npx",
      "args": ["github:ferronicardoso/mcp-postgresql"],
      "env": {
        "PGHOST": "localhost",
        "PGPORT": "5432",
        "PGDATABASE": "postgres",
        "PGUSER": "postgres",
        "PGPASSWORD": "your-password"
      }
    }
  }
}

Configuración MCP de VS Code

.vscode/mcp.json:

{
  "servers": {
    "postgresql": {
      "command": "npx",
      "args": ["github:ferronicardoso/mcp-postgresql"],
      "env": {
        "PGHOST": "localhost",
        "PGPORT": "5432",
        "PGDATABASE": "postgres",
        "PGUSER": "postgres",
        "PGPASSWORD": "your-password"
      }
    }
  }
}

Ejecutar con Docker (transporte HTTP)

La imagen publicada se ejecuta en modo HTTP Streamable por defecto, para usar como endpoint MCP remoto (por ejemplo, desde el nodo Cliente MCP de n8n o cualquier cliente compatible con HTTP Streamable):

Bash (Linux/macOS/WSL):

docker run -d --name mcp-postgresql \
  -p 3002:3002 \
  -e PGHOST=host.docker.internal \
  -e PGPORT=5432 \
  -e PGDATABASE=postgres \
  -e PGUSER=postgres \
  -e PGPASSWORD=your-password \
  ghcr.io/ferronicardoso/mcp-postgresql:latest

PowerShell:

docker run -d --name mcp-postgresql `
  -p 3002:3002 `
  -e PGHOST=host.docker.internal `
  -e PGPORT=5432 `
  -e PGDATABASE=postgres `
  -e PGUSER=postgres `
  -e PGPASSWORD=your-password `
  ghcr.io/ferronicardoso/mcp-postgresql:latest

El endpoint MCP está disponible en http://localhost:3002/mcp.

Desarrollo local

git clone https://github.com/ferronicardoso/mcp-postgresql
cd mcp-postgresql
npm install
npm run build

Inicia el servidor compilado:

npm start

Flujo de trabajo de compilación y commit

Este repositorio rastrea intencionalmente dist/ para soportar el uso de npx github:usuario/repo.

El proyecto utiliza un hook pre-commit de Husky para:

1. compilar TypeScript (npm run build)

2. preparar los artefactos generados (git add dist)

Alternativa manual:

npm run build
git add dist

Notas de seguridad

• Nunca hagas commit de credenciales reales o archivos .env.

• Prefiere usuarios de base de datos con mínimos privilegios para uso en producción.

• Para redes públicas o no confiables, habilita el cifrado (PGSSL=true) y configura los certificados adecuadamente.

Licencia

MIT © Raphael Augusto Ferroni Cardoso