pg-mcp

Servicio de consulta de PostgreSQL en lenguaje natural mediante MCP (Protocolo de Contexto de Modelo). Utiliza OpenAI para traducir lenguaje natural a SQL, lo valida y ejecuta de forma segura, y devuelve los resultados a cualquier cliente compatible con MCP.

Características

• Lenguaje natural a SQL mediante OpenAI

• Detección automática del esquema de la base de datos al iniciar (tablas, vistas, columnas, índices, claves foráneas, enums)

• Caché de esquema con persistencia en disco opcional

• Validación de seguridad SQL (solo SELECT, bloqueo de funciones peligrosas, aplicación de límites LIMIT)

• Ejecución de transacciones de solo lectura con tiempo de espera configurable

• Validación de resultados con reintento automático en caso de resultados vacíos

• Soporta múltiples bases de datos

Related MCP server: PostgreSQL MCP Server

Requisitos

• Python 3.11+

• PostgreSQL

• Clave de API de OpenAI

Instalación

pip install -e .

Para desarrollo:

pip install -e ".[dev]"

Configuración

Copia .env.example a .env y rellena tus valores:

cp .env.example .env

Ejemplo con múltiples bases de datos:

PG_MCP_DATABASES=postgresql://user:pass@host1:5432/db1,postgresql://user:pass@host2:5432/db2

Uso con Claude Desktop

Añade a tu claude_desktop_config.json:

{
  "mcpServers": {
    "pg-mcp": {
      "command": "pg-mcp",
      "args": [],
      "env": {
        "PG_MCP_DATABASES": "postgresql://user:pass@localhost:5432/mydb",
        "OPENAI_API_KEY": "sk-...",
        "PG_MCP_SCHEMA_CACHE_PATH": "~/.cache/pg-mcp/schema.json"
      }
    }
  }
}

Herramientas MCP

query

Consulta una base de datos usando lenguaje natural.

{
  "question": "What are the top 10 customers by sales last month?",
  "database": "mydb",
  "return_sql": false,
  "max_rows": 100
}

• return_sql: true — devuelve el SQL generado sin ejecutarlo

• return_sql: false (por defecto) — ejecuta y devuelve los resultados

list_databases

Lista todas las bases de datos accesibles con información resumida.

describe_database

Obtén información detallada del esquema de una base de datos.

{
  "database": "mydb",
  "schema": "public",
  "pattern": "user"
}

refresh_schema

Recarga la caché del esquema desde la base de datos.

{
  "database": "mydb"
}

Omite database para refrescar todas las bases de datos.

Pruebas con bases de datos de ejemplo (Fixture)

El directorio fixtures/ proporciona tres bases de datos preconstruidas para pruebas locales.

Configuración

# From project root, create & seed all fixture databases
cd fixtures
make all

# Or create individual ones
make small     # pg_mcp_test_small  — bookshelf (4 tables, ~50 rows)
make medium    # pg_mcp_test_medium — ecommerce (12 tables, ~500 rows)
make large     # pg_mcp_test_large  — enterprise (28 tables, ~5000 rows)

Sobrescribe las credenciales de PostgreSQL mediante variables de entorno (por defecto: root / admin123 @ localhost:5432):

make all PGUSER=myuser PGPASSWORD=mypass PGHOST=127.0.0.1

Configurar .env

Apunta PG_MCP_DATABASES a las bases de datos de ejemplo:

PG_MCP_DATABASES=postgresql://root:admin123@localhost:5432/pg_mcp_test_small,postgresql://root:admin123@localhost:5432/pg_mcp_test_medium,postgresql://root:admin123@localhost:5432/pg_mcp_test_large

Probar con el Inspector MCP

Utiliza el inspector MCP integrado para pruebas interactivas:

cd /path/to/postgres-mcp
fastmcp dev src/pg_mcp/server.py:mcp

Esto abre una interfaz de usuario en el navegador donde puedes llamar a herramientas como query, list_databases y describe_database directamente.

Probar con Claude Desktop

Añade a claude_desktop_config.json:

{
  "mcpServers": {
    "pg-mcp": {
      "command": "python3",
      "args": ["-m", "pg_mcp.server"],
      "cwd": "/path/to/postgres-mcp"
    }
  }
}

Nota: Al usar cwd, el servidor lee .env desde ese directorio. También puedes pasar variables de entorno a través de la clave "env".

Consultas de prueba

Una vez conectado, prueba estas consultas en lenguaje natural contra las bases de datos de ejemplo:

Limpieza

cd fixtures
make drop-all      # Remove all fixture databases
make refresh-all   # Drop + recreate + re-seed

Ejecución de pruebas

python3 -m pytest tests/ -v

Cómo funciona

User question
  → Schema context assembled from cache
  → OpenAI generates SQL
  → Safety validation (SELECT-only, no dangerous functions, LIMIT injection)
  → Execute in read-only transaction with timeout
  → Optional result validation on empty results
  → Return SQL or query results

Seguridad

• El SQL generado se valida para asegurar que sea solo de tipo SELECT (incluyendo comprobaciones de CTE)

• Se bloquean más de 40 funciones peligrosas de PostgreSQL (control de sesión, bloqueos consultivos, dblink, acceso al sistema de archivos, mutación de secuencias, etc.)

• Todas las consultas se ejecutan en transacciones de solo lectura

• La aplicación automática de LIMIT evita conjuntos de resultados masivos

• El tiempo de espera de consulta evita consultas de larga duración

• Las contraseñas de conexión nunca aparecen en los registros ni en las respuestas de la API