PostgreSQL MCP Server

Servidor MCP (Model Context Protocol) para acceso de solo lectura a bases de datos PostgreSQL.

Características

Este servidor MCP proporciona herramientas para:

• 📋 Listar tablas disponibles en la base de datos
• 🔍 Ver estructura completa de tablas (columnas, tipos, constraints, índices)
• 📊 Obtener estadísticas de tablas (filas, tamaño, última actualización)
• 🔎 Ejecutar queries SELECT de solo lectura (protegido contra operaciones de escritura)

Instalación

# Instalar dependencias
npm install

# Compilar el proyecto
npm run build

Configuración en Claude Desktop

Agrega la configuración del servidor MCP en tu archivo de configuración de Claude Desktop:

macOS

Edita: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows

Edita: %APPDATA%\Claude\claude_desktop_config.json

Configuración:

{
  "mcpServers": {
    "postgres-mcp": {
      "command": "node",
      "args": [
        "/ruta/absoluta/a/postgres-mcp/build/index.js"
      ],
      "env": {
        "PGHOST": "localhost",
        "PGPORT": "5432",
        "PGDATABASE": "tu_base_de_datos",
        "PGUSER": "tu_usuario",
        "PGPASSWORD": "tu_password"
      }
    }
  }
}

Importante: Reemplaza /ruta/absoluta/a/postgres-mcp con la ruta real donde clonaste el proyecto.

Herramientas Disponibles

1. list_tables

Lista todas las tablas en un schema.

Parámetros:

• schema (opcional): Nombre del schema (por defecto: 'public')

Ejemplo de uso:

Lista todas las tablas de la base de datos

2. describe_table

Muestra la estructura completa de una tabla.

Parámetros:

• table_name (requerido): Nombre de la tabla
• schema (opcional): Nombre del schema (por defecto: 'public')

Ejemplo de uso:

Muéstrame la estructura de la tabla users

3. query

Ejecuta una consulta SELECT de solo lectura.

Parámetros:

• sql (requerido): Consulta SQL SELECT
• limit (opcional): Límite de filas a retornar (por defecto: 100)

Ejemplo de uso:

Ejecuta esta query: SELECT * FROM users WHERE active = true

4. table_stats

Obtiene estadísticas de una tabla.

Parámetros:

• table_name (requerido): Nombre de la tabla
• schema (opcional): Nombre del schema (por defecto: 'public')

Ejemplo de uso:

Muéstrame las estadísticas de la tabla products

Seguridad

🔒 Este servidor está diseñado para ser de solo lectura:

• Solo permite consultas SELECT
• Bloquea operaciones: INSERT, UPDATE, DELETE, DROP, CREATE, ALTER, TRUNCATE, etc.
• Aplica límites automáticos a las consultas que no especifican LIMIT

Desarrollo

# Compilar en modo watch
npm run watch

# Ejecutar en desarrollo
npm start

Troubleshooting

Error de conexión a PostgreSQL

• Verifica que PostgreSQL esté corriendo
• Confirma las credenciales en el archivo .env
• Verifica que el usuario tenga permisos de lectura en la base de datos

El servidor no aparece en Claude Desktop

• Asegúrate de haber reiniciado Claude Desktop después de editar la configuración
• Verifica que la ruta al archivo build/index.js sea absoluta y correcta
• Revisa los logs de Claude Desktop para ver errores

"Query no permitida"

• Solo se permiten consultas SELECT
• Asegúrate de no usar operaciones de escritura en tus queries