mcp-postgres

Servidor MCP para PostgreSQL. Proporciona a los agentes de IA inteligencia de esquemas, ejecución de consultas y herramientas de DBA, a través del Model Context Protocol.

A diferencia de los servidores MCP de bases de datos genéricos, mcp-postgres es nativo de Postgres. Extrae comentarios de tablas/columnas, entiende las vistas de catálogo específicas de Postgres, proporciona análisis de índices y se entrega con niveles de acceso configurables para que no otorgues a un LLM acceso ilimitado a la base de datos.

Características

Inteligencia de esquemas

• Listar esquemas, tablas y vistas con tamaños y recuentos de filas

• Descripciones completas de tablas: columnas, tipos, restricciones, índices, claves foráneas

• Extrae metadatos COMMENT ON: proporciona al LLM contexto semántico sobre el significado de las columnas

• Buscar objetos por nombre o comentario en toda la base de datos

Ejecución de consultas

• Herramienta query de solo lectura con límite automático de filas

• Herramienta execute con capacidad de escritura limitada por nivel de acceso

• EXPLAIN ANALYZE con salida legible para humanos

Herramientas de DBA

• Estadísticas de tablas: tuplas activas/muertas, porcentaje de bloat, historial de vacuum, patrones de escaneo

• Análisis de índices: estadísticas de uso, detección de índices no utilizados, sugerencias de índices faltantes

• Salud de la base de datos: conexiones, ratio de aciertos de caché, consultas de larga duración, rendimiento

Seguridad

• Cuatro niveles de acceso: readonly, readwrite, admin, unrestricted

• Clasificación de sentencias SQL (SELECT, DML, DDL, admin) con cumplimiento

• Registro de auditoría en stderr (JSON, una entrada por consulta)

Inicio rápido

npx mcp-postgres --connection-string "postgres://user:pass@localhost:5432/mydb"

O con variables de entorno:

DATABASE_URL="postgres://user:pass@localhost:5432/mydb" npx mcp-postgres

Claude Desktop

Añadir a tu claude_desktop_config.json:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-postgres",
        "--connection-string",
        "postgres://user:pass@localhost:5432/mydb"
      ]
    }
  }
}

Claude Code

Añadir al .mcp.json de tu proyecto:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "mcp-postgres"],
      "env": {
        "DATABASE_URL": "postgres://user:pass@localhost:5432/mydb"
      }
    }
  }
}

Herramientas

*explain_query con analyze=true ejecuta la consulta, por lo que respeta el nivel de acceso de la sentencia.

Recursos

Prompts

Configuración

Opciones de CLI

--connection-string  PostgreSQL connection URL
--access-level       readonly|readwrite|admin|unrestricted (default: readonly)
--row-limit          Max rows returned per query (default: 500)
--schema             Default schema filter (default: public)
--audit              Enable query audit logging to stderr

Variables de entorno

Niveles de acceso

El valor predeterminado es readonly. Utiliza el nivel mínimo necesario.

Registro de auditoría

Habilitar con --audit. Registra cada invocación de herramienta en stderr como JSON:

{"timestamp":"2026-04-03T12:00:00.000Z","tool":"query","sql":"SELECT * FROM users","statementType":"select","accessLevel":"readonly","allowed":true,"durationMs":12,"rowCount":42}

Redirige stderr a un archivo para capturarlo: mcp-postgres --audit 2>audit.log

Arquitectura

src/
├── index.ts             Entry point and CLI
├── server.ts            MCP server setup
├── config.ts            Configuration parsing
├── db/
│   ├── pool.ts          Connection pool management
│   └── query.ts         Query execution with timing
├── tools/
│   ├── schema.ts        Schema exploration tools
│   ├── query.ts         Query execution tools
│   └── performance.ts   DBA and health tools
├── resources/
│   └── schema.ts        Schema DDL resources
├── prompts/
│   └── index.ts         Prompt templates
└── safety/
    ├── classifier.ts    SQL statement classification
    ├── access.ts        Access level enforcement
    └── audit.ts         Audit logging

Desarrollo

npm install
npm test           # run tests
npm run build      # compile TypeScript
npm run dev -- --connection-string "postgres://..."  # run in dev mode

Licencia

MIT