MCPg - Production-grade PostgreSQL MCP Server

Servidor de Protocolo de Contexto de Modelo PostgreSQL seguro por defecto para agentes de IA.

Documentación

MCPg

Un servidor Model Context Protocol de grado de producción para PostgreSQL. Permite que los agentes de IA inspeccionen, consulten, operen y ajusten una base de datos Postgres de forma segura — 254 herramientas que abarcan introspección de catálogo, inteligencia de consultas, SQL en lenguaje natural, diferencias estructurales, búsqueda híbrida, consultas de grafos, movimiento de datos, operaciones en vivo y más.

Pruébalo en vivo: apunta un cliente MCP — o el MCP Inspector — al endpoint de demostración alojado de solo lectura https://devopam-mcpg-demo.hf.space/mcp. Sirve herramientas de lectura contra datos de demostración desechables; para uso real, ejecuta MCPg junto a tu propia base de datos (consulta Inicio rápido).

📍 Listado en

Aspecto	MCPg
Seguridad	Solo lectura por defecto + validación AST
Transporte	stdio + HTTP/SSE
Instalación	`pip install mcpg`
Versiones de Postgres	14–19
Diferenciador clave	Observabilidad de producción + multi-tenant

Por qué MCPg

Seguro por defecto. Modo de acceso de solo lectura. Cada sentencia SQL proporcionada por el usuario se analiza mediante una lista blanca de AST validada antes de la ejecución. La interpolación de identificadores pasa por una estricta expresión regular [A-Za-z_][A-Za-z0-9_]* — una restricción de diseño que significa que la entrada del usuario nunca llega a la base de datos mediante concatenación de cadenas. Capacidades como DDL, shell y LISTEN/NOTIFY están desactivadas hasta que optes por ellas. Cada herramienta publica ToolAnnotations de MCP (readOnlyHint, openWorldHint) derivadas de esas mismas compuertas, para que los clientes puedan autoaprobar lecturas y controlar escrituras sin adivinar.
Un solo servidor, amplia superficie. Acceso a datos de aplicaciones (consultas, búsqueda, cursores, NL→SQL) y operaciones de nivel DBA (comprobaciones de salud, ajuste de índices, análisis EXPLAIN, bloqueos, vacuum, volcados, réplicas, migraciones) en un único servidor MCP. Los agentes no tienen que cambiar de herramientas para cambiar de tarea.
Todo nativo de PostgreSQL. Sin ORM, sin impuesto de abstracción — usa psycopg3 directamente, habla con cada vista del sistema pg_*, se integra con TimescaleDB, pgvector, PostGIS, Apache AGE y pg_stat_statements cuando están disponibles, y degrada con elegancia cuando no lo están.
Formado para producción, no para demostraciones. Agrupación de conexiones, multi-tenant por solicitud con SET ROLE, enrutamiento de réplicas de lectura con detección de hosts degradados, cursores del lado del servidor con conexiones dedicadas, limitación de velocidad, registro de auditoría con redacción por expresiones regulares, aplicación de TLS de PG al inicio, autenticación OIDC JWT bearer, tiempos de espera de sentencia / bloqueo por sesión.
Observabilidad integrada. Endpoint /metrics de Prometheus en el transporte HTTP expone mcpg_tool_calls_total{tool,status} + mcpg_tool_duration_seconds. Cada llamada a herramienta registra un evento de auditoría estructurado con argumentos con credenciales redactadas.
Impulsado por pruebas, multiversión. Más de 2.500 pruebas unitarias más una suite de integración que se ejecuta contra un contenedor real de PostgreSQL en CI — la matriz cubre PG 14, 15, 16, 17, 18 en cada push, además de PG 19 (beta) como entrada experimental (no bloqueante) rastreada bajo el issue #120.

Instalación

Desde PyPI (recomendado)

pip install mcpg
# or, in an isolated venv exposed globally:
uv tool install mcpg

Verifica:

mcpg --version

Docker

Extrae la imagen precompilada del Registro de Contenedores de GitHub (publicada en cada release etiquetado — :latest sigue la más reciente, o fija una versión como :0.6.5):

docker pull ghcr.io/devopam/mcpg:latest
docker run --rm --name mcpg -p 8000:8000 \
    -e MCPG_DATABASE_URL=postgresql://user:pass@host:5432/db \
    -e MCPG_ACCESS_MODE=read-only \
    ghcr.io/devopam/mcpg:latest

En Windows PowerShell reemplaza el \ final con un backtick ` (o pon el comando en una sola línea); la guía de instalación tiene bloques listos para copiar para Linux/macOS, PowerShell y Command Prompt.

O constrúyela tú mismo desde el código fuente:

docker build -t mcpg https://github.com/devopam/MCPg.git

Imagen de múltiples etapas: la etapa de ejecución elimina el toolchain de compilación, se ejecuta como uid=10001 / gid=10001 con shell nologin, archivos de aplicación propiedad de root y de solo lectura para el usuario de ejecución.

Desde el código fuente (desarrolladores)

git clone https://github.com/devopam/MCPg && cd MCPg
uv sync

uv sync crea un venv con todas las dependencias de ejecución + desarrollo y expone el script de consola mcpg.

Más detalles en la Guía de Instalación.

Inicio rápido

Instalaciones de un clic: — configuración para Windsurf, JetBrains, Zed, Cline, Antigravity, Qwen Code, Perplexity, ChatGPT, Copilot Studio, Continue y clientes HTTP en la guía de integraciones.

Instalación de un clic en Claude Desktop (.mcpb)

Descarga mcpg-<version>.mcpb del último release y haz doble clic en él (o arrástralo a Configuración de Claude Desktop → Extensiones). Se te pedirá tu URL de conexión de PostgreSQL — almacenada en el llavero del sistema operativo — y un modo de acceso (por defecto solo lectura). Eso es toda la instalación: el paquete es de ~2 kB y el host resuelve el release fijado de mcpg desde PyPI para tu plataforma.

O conéctalo manualmente (transporte stdio)

Coloca esto en tu claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json; Windows: %APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "mcpg": {
      "command": "uvx",
      "args": ["mcpg"],
      "env": {
        "MCPG_DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb"
      }
    }
  }
}

Reinicia Claude Desktop. El conjunto de herramientas de MCPg ahora está disponible para el modelo. Puedes preguntarle a Claude cosas como:

"¿Qué esquemas existen en esta base de datos? Para cada uno, resume las tres tablas más grandes."

"¿Por qué esta consulta es lenta? SELECT * FROM orders WHERE customer_id = 42 ORDER BY created_at DESC"

¿Aún no tienes datos interesantes? Siembra el conjunto de datos de demostración

MCPG_DATABASE_URL=postgresql://... mcpg --demo

Un comando siembra un pequeño conjunto de datos de comercio electrónico curado (3.000 pedidos, 900 reseñas de productos, fallos plantados deliberadamente) en un esquema mcpg_demo — diseñado para que el asesor de índices, el análisis de planes de consulta, la búsqueda de texto completo, la auditoría de PII y la proyección de grafos tengan algo real que encontrar en tu primer intento. Consulta el recorrido guiado para ver una demostración capturada, y elimínalo en cualquier momento con mcpg --demo-drop.

Ejecutar como servidor HTTP (para integraciones de IDE, aplicaciones web, etc.)

MCPG_DATABASE_URL=postgresql://user:pass@localhost:5432/mydb \
MCPG_TRANSPORT=streamable-http \
MCPG_HTTP_PORT=8000 \
mcpg

Luego apunta cualquier cliente compatible con MCP a http://localhost:8000/mcp (o /sse para el transporte SSE). El transporte HTTP se niega a iniciar a menos que esté autenticado — establece MCPG_HTTP_AUTH_TOKEN=... para un bearer estático, o MCPG_AUTH_MODE=oidc para validación JWT completa contra un emisor OIDC. Para ejecutar deliberadamente sin autenticación (no recomendado), establece MCPG_HTTP_ALLOW_UNAUTHENTICATED=true.

Configuración

MCPg se configura enteramente mediante variables de entorno — sin archivo de configuración, sin banderas (los --version / --demo / --demo-drop de la CLI son comandos de una sola ejecución, no configuración). La única obligatoria es MCPG_DATABASE_URL; todo lo demás tiene un valor predeterminado seguro.

Escenarios comunes

Escenario	Establecer
Exploración local, solo lectura	`MCPG_DATABASE_URL`
Acceso de escritura a datos de aplicación	`MCPG_ACCESS_MODE=restricted`
Kit de herramientas DBA (DDL, vacuum, etc.)	`MCPG_ACCESS_MODE=unrestricted` + `MCPG_ALLOW_DDL=true`
Transporte HTTP con autenticación bearer	`MCPG_TRANSPORT=streamable-http` + `MCPG_HTTP_AUTH_TOKEN=…`
SaaS multi-tenant	`MCPG_DEFAULT_ROLE=tenant_a` + `MCPG_ALLOWED_ROLES=tenant_a,tenant_b,…`
Distribución de réplicas de lectura	`MCPG_REPLICA_URLS=postgresql://…?sslmode=require,postgresql://…?sslmode=require`
NL→SQL — proveedor único	Establece cualquier clave de proveedor (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `XAI_API_KEY`, `GROQ_API_KEY`, `HF_TOKEN`, … — 22 proveedores integrados). MCPg elige automáticamente el predeterminado.
NL→SQL — múltiples proveedores, el llamador elige	Establece todas las claves de proveedor que quieras activas. Cada llamada a `translate_nl_to_sql` puede pasar `provider="…"` (cualquier integrado o personalizado configurado).

Referencia completa

Núcleo

Variable	Predeterminado	Descripción
`MCPG_DATABASE_URL`	obligatoria	DSN principal de PostgreSQL. Admite formas URI (`postgresql://…`) y de palabra clave (`host=… user=…`). Los hosts remotos requieren `sslmode=require` (o más fuerte).
`MCPG_ACCESS_MODE`	`read-only`	`read-only` \| `restricted` (permite herramientas de escritura) \| `unrestricted` (también desbloquea herramientas DBA cuando se combina con las variables de compuerta).
`MCPG_TRANSPORT`	`stdio`	`stdio` (predeterminado, para Claude Desktop) \| `streamable-http` \| `sse`.
`MCPG_LOG_LEVEL`	`INFO`	`DEBUG` \| `INFO` \| `WARNING` \| `ERROR` \| `CRITICAL`.
`MCPG_HTTP_HOST`	`127.0.0.1`	Dirección de enlace para transportes HTTP. Establece a `0.0.0.0` dentro de contenedores.
`MCPG_HTTP_PORT`	`8000`	Puerto de escucha para transportes HTTP (1–65535).

Compuertas de capacidad (opt-in para herramientas de mayor radio de impacto)

Variable	Predeterminado	Descripción
`MCPG_ALLOW_DDL`	`false`	Expone herramientas DDL (`run_ddl`, `create_graph`, `drop_graph`, herramientas de hypertable, herramientas de migración). Requiere `MCPG_ACCESS_MODE=unrestricted`.
`MCPG_ALLOW_SHELL`	`false`	Expone herramientas respaldadas por subprocesos (`dump_database`, `restore_database`, `run_pg_binary`). Los binarios de cliente PG requeridos deben estar en `PATH`.
`MCPG_ALLOW_LISTEN`	`false`	Expone herramientas `LISTEN/NOTIFY` (`subscribe_channel`, `poll_notifications`, `unsubscribe_channel`, `list_notification_subscriptions`).

Autenticación (solo transportes HTTP)

Variable	Predeterminado	Descripción
`MCPG_AUTH_MODE`	`static`	`static` (compara bearer con `MCPG_HTTP_AUTH_TOKEN`) \| `oidc` (validación JWT completa).
`MCPG_HTTP_AUTH_TOKEN`	—	Token bearer requerido cuando `MCPG_AUTH_MODE=static`. Comparación en tiempo constante. El transporte HTTP se niega a iniciar (`ConfigError`) a menos que esto, `MCPG_AUTH_MODE=oidc` o `MCPG_HTTP_ALLOW_UNAUTHENTICATED=true` esté establecido.
`MCPG_HTTP_ALLOW_UNAUTHENTICATED`	`false`	Opt-out explícito de la verificación de autenticación de cierre ante fallo del transporte HTTP. Se registra ruidosamente en cada inicio cuando se establece; no recomendado.
`MCPG_OIDC_ISSUER`	—	URL del emisor OIDC (requerida cuando `MCPG_AUTH_MODE=oidc`).
`MCPG_OIDC_AUDIENCE`	—	Reclamación `aud` esperada (requerida cuando `MCPG_AUTH_MODE=oidc`).
`MCPG_OIDC_JWKS_URL`	descubierto	Anula el endpoint JWKS (auto-descubierto desde el `.well-known` del emisor en caso contrario).
`MCPG_OIDC_ROLE_CLAIM`	—	Reclamación JWT cuyo valor se convierte en el rol de PG por solicitud (`SET LOCAL ROLE`). Se compone con el controlador de tenencia.

Endurecimiento HTTP (solo transportes HTTP)

Variable	Predeterminado	Descripción
`MCPG_HTTP_MAX_BODY_BYTES`	`1048576`	(1 MiB) Los cuerpos de solicitud por encima de esto reciben un `413`. Cuenta los bytes transmitidos, por lo que un `Content-Length` faltante o falso no puede evadirlo.
`MCPG_HTTP_ALLOWED_ORIGINS`	—	Lista de permitidos CORS separada por comas. Sin establecer = sin middleware CORS (sin encabezados de origen cruzado emitidos).
`MCPG_HTTP_HSTS_MAX_AGE`	`63072000`	`Strict-Transport-Security` max-age (2 años, la recomendación actual de OWASP). `0` desactiva el encabezado HSTS. Los encabezados de seguridad (CSP, X-Frame-Options, X-Content-Type-Options, Referrer-Policy) siempre se agregan a menos que la aplicación ya los haya establecido.
`MCPG_HTTP_REQUEST_TIMEOUT_SECONDS`	`0`	Límite de tiempo de pared por solicitud (`504` al expirar). `0` = desactivado. Déjalo desactivado si dependes de flujos SSE / HTTP transmitibles de larga duración — un límite duro también los corta.
`MCPG_HTTP_TRUSTED_HOSTS`	—	Lista separada por comas de valores de encabezado `Host` permitidos (se admiten comodines como `*.example.com`). Sin establecer = sin validación de encabezado de host (comportamiento actual). Cuando se establece, las solicitudes con un Host que no coincide reciben un `400` mediante el `TrustedHostMiddleware` de Starlette.

Multi-tenencia (`SET ROLE`)

Variable	Predeterminado	Descripción
`MCPG_DEFAULT_ROLE`	—	Rol estático de PG aplicado a cada consulta. Validado como identificador.
`MCPG_ALLOWED_ROLES`	—	Lista de permitidos separada por comas. Cuando se establece, el encabezado `X-MCPG-Role` / la reclamación de rol OIDC debe estar en esta lista.

Réplicas de lectura

Variable	Predeterminado	Descripción
`MCPG_REPLICA_URLS`	—	DSNs de réplica separados por comas. Las consultas `force_readonly` se distribuyen en round-robin entre réplicas saludables; respaldo a primaria en caso de fallo; ventana de reintento de réplica degradada de 30 s.

Múltiples bases de datos (secundarias de solo lectura)

Variable	Predeterminado	Descripción
`MCPG_SECONDARY_DATABASE_URLS`	—	Entradas `name=dsn` separadas por comas o nuevas líneas que nombran bases de datos adicionales de solo lectura que este servidor puede atender (p. ej., `analytics=postgresql://…?sslmode=require,reporting=postgresql://…?sslmode=require`). Las herramientas con capacidad de lectura aceptan un argumento opcional `database` para seleccionar una secundaria por nombre; omítelo para la primaria. Las secundarias son de solo lectura — impuesto por PostgreSQL (cada consulta se ejecuta en una transacción `READ ONLY`), por lo que escrituras / DDL / shell / migraciones siempre apuntan a la primaria. Los nombres deben ser identificadores simples (`[a-z0-9_]+`), únicos y no `primary` (el id reservado de `MCPG_DATABASE_URL`). Mismas reglas TLS que el DSN primario. Llama a `list_databases` para descubrir los ids configurados y su alcanzabilidad.

Pool / tiempos de espera / TLS

Variable	Predeterminado	Descripción
`MCPG_POOL_MIN_SIZE`	`1`	Conexiones mínimas del pool.
`MCPG_POOL_MAX_SIZE`	`5`	Conexiones máximas del pool. Debe ser ≥ `MCPG_POOL_MIN_SIZE`.
`MCPG_STATEMENT_TIMEOUT_MS`	`30000`	`statement_timeout` por sesión establecido al obtener la conexión. Las consultas descontroladas se autoterminan.
`MCPG_LOCK_TIMEOUT_MS`	`5000`	`lock_timeout` por sesión. Las esperas de bloqueo colgadas se autoterminan.
`MCPG_ENABLE_ANALYTICAL_QUERIES`	`true`	Exponer `run_analytical_query` (lecturas de larga duración en un pool aislado). Establece `false` para retirar la herramienta.
`MCPG_ANALYTICAL_TIMEOUT_MS`	`120000`	Presupuesto por llamada predeterminado para `run_analytical_query` (2 min).
`MCPG_ANALYTICAL_MAX_TIMEOUT_MS`	`600000`	Límite máximo para `run_analytical_query`; un `timeout_ms` por llamada se ajusta a este límite (10 min). Debe ser ≥ `MCPG_ANALYTICAL_TIMEOUT_MS`.
`MCPG_ANALYTICAL_MAX_CONCURRENCY`	`2`	Tamaño del pool analítico aislado — máximo de llamadas `run_analytical_query` simultáneas.
`MCPG_ALLOW_INSECURE_TLS`	`false`	Omitir la verificación TLS de inicio que rechaza DSNs remotos sin `sslmode=require` (o más fuerte). Los hosts de loopback siempre están exentos.
`MCPG_SHUTDOWN_DRAIN_SECONDS`	`30`	En SIGTERM, esperar hasta este tiempo para que las llamadas de herramientas en curso terminen antes de cerrar el pool y los cursores.

Herramientas de subproceso (solo `MCPG_ALLOW_SHELL=true`)

Variable	Predeterminado	Descripción
`MCPG_SHELL_TIMEOUT_SEC`	`60`	Tiempo máximo de pared para invocaciones de `pg_dump` / `pg_restore` / `psql`.
`MCPG_SHELL_MAX_OUTPUT_BYTES`	`67108864`	(64 MiB) Límite en stdout capturado por llamada de subproceso.
`MCPG_SUBPROCESS_BIN_ALLOWLIST`	—	Directorios absolutos separados por comas bajo los cuales deben residir los `pg_dump` / `pg_restore` / `psql` resueltos. Vacío = confiar en `PATH`. Anula un shim de PATH de estos binarios.
`MCPG_SUBPROCESS_CPU_SECONDS`	—	`RLIMIT_CPU` por hijo (segundos). Solo POSIX; sin establecer = heredar.
`MCPG_SUBPROCESS_MEMORY_MB`	—	`RLIMIT_AS` por hijo (MiB). Solo POSIX; sin establecer = heredar.

LISTEN/NOTIFY (solo `MCPG_ALLOW_LISTEN=true`)

Variable	Predeterminado	Descripción
`MCPG_LISTEN_QUEUE_MAX`	`1000`	Buffer por canal; las notificaciones más antiguas se descartan en desbordamiento.

Auditoría

Variable	Predeterminado	Descripción
`MCPG_AUDIT_PERSIST`	`false`	Cuando es verdadero, cada llamada a `run_write` / `run_ddl` persiste en una tabla `mcpg_audit.events` (auto-creada idempotentemente).
`MCPG_AUDIT_REDACT_KEYS`	—	Fragmentos de regex separados por comas añadidos al patrón de nombres de secretos (los predeterminados ya cubren `password`, `passwd`, `secret`, `token`, `api[_-]?key`, `bearer`, `authorization`, `database_url`, `dsn`, `conninfo`).
`MCPG_AUDIT_INTEGRITY`	`false`	Cuando es verdadero, cada evento persistido se firma con un HMAC encadenado sobre el evento anterior; la herramienta `verify_audit_chain` recorre la cadena e informa la primera ruptura. Requiere `MCPG_AUDIT_HMAC_KEY`.
`MCPG_AUDIT_HMAC_KEY`	—	Clave secreta para la cadena HMAC de auditoría. Requerida cuando `MCPG_AUDIT_INTEGRITY=true`. Nunca aparece en `repr`/registros.

Backend de secretos

Por defecto, cada secreto se lee directamente del entorno. Establece MCPG_SECRETS_BACKEND=file para cargar en su lugar claves API / token de portador / clave HMAC desde un archivo montado — un nombre en el archivo gana; cualquier cosa ausente cae de vuelta a la variable de entorno, por lo que los archivos parciales funcionan.

Variable	Predeterminado	Descripción
`MCPG_SECRETS_BACKEND`	`env`	`env` (leer cada secreto del entorno) \| `file` (superponer un archivo de secretos sobre el entorno).
`MCPG_SECRETS_FILE_PATH`	—	Requerido cuando `MCPG_SECRETS_BACKEND=file`. Ruta a un mapa `name → value` plano: JSON siempre, o YAML (`.yaml`/`.yml`) cuando PyYAML está instalado. Cubre `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `GEMINI_API_KEY` / `GOOGLE_API_KEY` / `MCPG_NL2SQL_API_KEY`, `MCPG_HTTP_AUTH_TOKEN`, y `MCPG_AUDIT_HMAC_KEY`.

Limitación de tasa

Variable	Predeterminado	Descripción
`MCPG_RATE_LIMIT_ENABLED`	`true`	Limitación de tasa por herramienta con token-bucket. Establece a `false` para restaurar el comportamiento ilimitado anterior al cambio disruptivo.
`MCPG_RATE_LIMIT_MAX_REQUESTS`	`60`	Límite global por ventana en todas las herramientas.
`MCPG_RATE_LIMIT_WINDOW_SECONDS`	`60`	Longitud de ventana para la cuota global.
`MCPG_RATE_LIMIT_HEAVY_MAX`	`5`	Límite para herramientas pesadas (`run_write`, `run_ddl`, `dump_database`, etc.).
`MCPG_RATE_LIMIT_HEAVY_WINDOW`	`60`	Longitud de ventana para la cuota de herramientas pesadas.

Caché y banderas de características

Variable	Predeterminado	Descripción
`MCPG_CACHE_ENABLED`	`true`	Habilitar o deshabilitar la capa de caché adaptativa.
`MCPG_CACHE_TTL_SECONDS`	`300`	Tiempo de vida de caché predeterminado en segundos.
`MCPG_CACHE_MAXSIZE`	`1024`	Límite máximo de capacidad LRU para la caché en memoria.
`MCPG_REDIS_URL`	—	Cadena de conexión opcional de backend Redis para caché externa y multi-nodo.
`MCPG_ENABLE_HEAVY_DIAGNOSTICS`	`true`	Alternar herramientas de diagnóstico, diagramas y asesoramiento computacionalmente pesadas.
`MCPG_ELICIT_CONFIRM_WRITES`	`false`	Cuando es verdadero, cada llamada de herramienta de escritura/DDL/shell/listen/migración (cualquier herramienta cuya anotación `readOnlyHint` no sea verdadera) requiere una confirmación interactiva aceptada (`ctx.elicit()`) antes de ejecutarse. Mejor esfuerzo, no un límite de cumplimiento: solo se activa para clientes que pasan una solicitud `context` y declaran la capacidad `elicitation` durante `initialize` — un cliente que omite cualquiera de los dos omite silenciosamente la puerta y la herramienta se ejecuta normalmente.

SQL en lenguaje natural

MCPg auto-descubre cada proveedor configurado desde el entorno al inicio — establece tantas claves de proveedor como tengas y cada una se vuelve invocable. Diecinueve proveedores vienen integrados. Tres son de primera parte (Anthropic, OpenAI, Gemini); los otros dieciséis hablan la API compatible con OpenAI con endpoints preestablecidos por proveedor: DeepSeek, Qwen, OpenRouter, Perplexity, xAI (Grok), Groq, Mistral, Together, Fireworks, DeepInfra, Cerebras, Nebius, Hugging Face, GitHub Models, SambaNova, y Moonshot (Kimi). Cada integrado es plug-and-play — establece la variable de entorno de clave API convencional del proveedor y se auto-descubre — y cualquier otro proveedor compatible con OpenAI o servidor de modelos local (Ollama, vLLM, LM Studio) sigue siendo conectable solo mediante configuración a través de MCPG_NL2SQL_CUSTOM_PROVIDERS. Toda la lista integrada es un registro declarativo en nl2sql.py, por lo que agregar un proveedor o actualizar un modelo predeterminado retirado es un cambio de datos de una línea.

Cuando MCPG_NL2SQL_PROVIDER no está establecido, MCPg auto-elige el predeterminado en orden de registro — anthropic → openai → gemini permanecen primero para que las implementaciones existentes no se vean afectadas. translate_nl_to_sql acepta un argumento opcional provider="…" para enrutar por llamada; get_server_info informa cuáles están configurados.

Variable	Predeterminado	Descripción
`<VENDOR>_API_KEY`	—	Establecer la clave convencional de un proveedor habilita ese proveedor. Slugs estándar: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `DEEPSEEK_API_KEY`, `OPENROUTER_API_KEY`, `PERPLEXITY_API_KEY`, `XAI_API_KEY`, `GROQ_API_KEY`, `MISTRAL_API_KEY`, `TOGETHER_API_KEY`, `FIREWORKS_API_KEY`, `CEREBRAS_API_KEY`, `NEBIUS_API_KEY`, `SAMBANOVA_API_KEY`, `MOONSHOT_API_KEY`.
(claves que se desvían)	—	Algunos proveedores no siguen `<VENDOR>_API_KEY`: Gemini → `GEMINI_API_KEY` o `GOOGLE_API_KEY`; Qwen → `DASHSCOPE_API_KEY` o `QWEN_API_KEY`; Hugging Face → `HF_TOKEN`; GitHub Models → `GITHUB_TOKEN`; DeepInfra → `DEEPINFRA_TOKEN`.
`MCPG_NL2SQL_PROVIDER`	auto-elegido	Cualquier slug integrado (listado arriba) o un nombre personalizado. Fija el proveedor predeterminado usado cuando la herramienta se llama sin `provider=`. Sin establecer + cualquier clave de proveedor presente → MCPg auto-elige en orden de registro.
`MCPG_NL2SQL_API_KEY`	—	Clave explícita para el `MCPG_NL2SQL_PROVIDER` configurado. Anula la variable de entorno convencional del proveedor solo para ese proveedor. Requiere que `MCPG_NL2SQL_PROVIDER` esté establecido.
`MCPG_NL2SQL_MODEL`	predeterminado del proveedor	Anular el modelo predeterminado (p. ej., `claude-sonnet-4-6`, `gpt-4o-mini`, `grok-3-mini`). Se aplica solo al proveedor predeterminado.
`MCPG_NL2SQL_BASE_URL`	—	Anulación de endpoint para el proveedor predeterminado (puertas de enlace privadas / endpoints regionales).
`MCPG_NL2SQL_CUSTOM_PROVIDERS`	—	Trae tu propio proveedor — sin cambio de código. Entradas `name=base_url\|model` separadas por comas/nuevas líneas que declaran proveedores extra compatibles con OpenAI más allá de los integrados (Ollama local / vLLM / LM Studio, o cualquier proveedor de nicho). Clave de `<NAME>_API_KEY` por convención, o agrega `\|KEY_ENV_VAR` para los que se desvían; sin clave permitido para endpoints de loopback. Cada nombre se vuelve invocable a través de `provider=`.
`MCPG_NL2SQL_MAX_TOKENS`	`2048`	Límite en tokens generados (límite duro: 16384).

Ejemplos de uso

Las herramientas MCP son invocadas por el agente (Claude, Cursor, Continue, …) en respuesta a tus instrucciones en lenguaje natural. Un puñado de idas y vueltas ilustrativas:

Inspeccionar el esquema

Tú: ¿Qué tablas viven en el esquema public, y cuáles son las más grandes por número de filas?

Agente (usando list_tables + summarize_table × N): Seis tablas: customers (1.2M filas), orders (4.7M), line_items (18.3M), products (340), addresses (1.4M), audit_log (45.8M — la más grande, acumula sin retención).

Diagnosticar una consulta lenta

Tú: ¿Por qué SELECT * FROM orders o JOIN line_items l ON o.id = l.order_id WHERE o.created_at > now() - interval '7 days' tarda 8 segundos?

Agente (usando why_is_this_slow + recommend_indexes): EXPLAIN ANALYZE muestra un escaneo secuencial sobre orders (4.7M filas) filtrado por created_at. No hay índice en orders.created_at. Recomendado: CREATE INDEX CONCURRENTLY orders_created_at_idx ON orders (created_at DESC); Mejora esperada: ~95% de reducción (el escaneo de índice toca ~33K filas en lugar de la tabla completa). Ejecuta validate_migration sobre él antes de aplicar para confirmar que no hay sorpresas de bloqueo.

Traducir inglés simple a SQL

Tú: Encuentra clientes que hicieron un pedido este mes pero nunca en los tres meses anteriores — muéstrame su correo electrónico y el gasto total de por vida actual. Agente (usando translate_nl_to_sql):

SELECT c.email, SUM(l.price * l.quantity) AS lifetime_spend
FROM customers c
JOIN orders o ON o.customer_id = c.id
JOIN line_items l ON l.order_id = o.id
WHERE EXISTS (
  SELECT 1 FROM orders o2 WHERE o2.customer_id = c.id
    AND o2.created_at >= date_trunc('month', now()))
  AND NOT EXISTS (
  SELECT 1 FROM orders o3 WHERE o3.customer_id = c.id
    AND o3.created_at >= date_trunc('month', now()) - interval '3 months'
    AND o3.created_at <  date_trunc('month', now()))
GROUP BY c.email;

Visualiza el esquema

Tú: Dibújame un diagrama ER del esquema public.

Agente (usando generate_schema_diagram): Devuelve un diagrama Mermaid que puedes pegar directamente en GitHub / Notion / Obsidian.

Audita la base de datos

Tú: ¿Qué tan saludable está esta base de datos ahora mismo?

Agente (usando audit_database): Devuelve un informe calificado: Puntuación de memoria y E/S 92 (BUENO), Transacciones y conexiones 78 (ADVERTENCIA: tasa de rollback 0.4%, revisa los logs de la aplicación), Concurrencia y bloqueos 60 (CRÍTICO: 14 backends en espera), Limpieza y bloat 88 (BUENO), Consultas lentas 70 (ADVERTENCIA: la plantilla de consulta principal se ejecuta 5000×, media 90 ms — ver optimize_query).

Ejecuta una escritura protegida

Tú: Soft-delete de cada pedido con más de 5 años de antigüedad.

Agente (usando run_write con MCPG_AUDIT_PERSIST=true): Valida la declaración a través del kernel SafeSQL, la ejecuta dentro de una transacción, devuelve el número de filas afectadas, persiste la llamada (sql + argumentos — con secretos redactados por regex — + estado) en mcpg_audit.events para revisión posterior.

Para docenas de recetas más — enrutamiento multi-tenant, pruebas de RLS, NL→SQL, búsqueda híbrida vector + FTS, Apache AGE Cypher, TimescaleDB, exportaciones de esquemas ORM, cursores del lado del servidor — consulta docs/cookbook.md.

Qué incluye

Lista de categorías compacta. Para la referencia completa y actual de herramientas, consulta docs/tools.md; para un recorrido guiado, consulta docs/tour.md.

Introspección de catálogo — esquemas, tablas, columnas, índices, restricciones, vistas, funciones, triggers, secuencias, particiones, políticas, roles, grants, enums, dominios, tipos compuestos, FDWs, publicaciones, suscripciones, extensiones, columnas generadas.
Inteligencia de consultas — run_select, run_select_parallel, explain_query, analyze_query_plan, why_is_this_slow, recommend_indexes, analyze_workload, check_database_health, detect_n_plus_one, audit_database.
Búsqueda — fuzzy_search (trigram), full_text_search, vector_search, hybrid_search (pgvector + FTS vía RRF), geo_search (PostGIS k-NN).
Lenguaje natural → SQL — translate_nl_to_sql (22 proveedores integrados — Anthropic, OpenAI, Gemini, xAI, Groq, Mistral, Hugging Face, … — además de cualquier endpoint personalizado compatible con OpenAI; la salida pasa por el mismo kernel SafeSQL que las consultas escritas a mano).
Visualización — generate_schema_diagram (ER), generate_fk_cascade_graph (radio de explosión de ON DELETE CASCADE), generate_graph_diagram (grafos de propiedades Apache AGE).
Diff estructural y migraciones — compare_schemas, validate_migration, flujo de trabajo escalonado prepare_migration / complete_migration / cancel_migration.
Apache AGE graph + Cypher — list_graphs, describe_graph, run_cypher, create_graph, drop_graph, generate_graph_diagram.
Herramientas compuestas y de asesoría — summarize_table, find_unused_objects, find_sensitive_columns (heurística PII), lint_naming_conventions, test_rls_for_role, list_locks, find_blocking_chains, read_pg_stat_io (PG16+), generate_test_data.
Operaciones en vivo y mantenimiento — list_active_queries, verify_connection_encryption (estado TLS del enlace en vivo), run_maintenance (VACUUM/ANALYZE), prune_audit_events (retención de auditoría), cancel_query, terminate_backend, run_write, run_ddl, enable_extension.
Movimiento de datos — export_query / export_table (CSV/JSON), dump_database / restore_database, import_csv / import_json (COPY FROM STDIN), copy_table_between_databases.
Cursores del lado del servidor — open_cursor, fetch_cursor, close_cursor, list_cursors para lecturas paginables sobre millones de filas.
TimescaleDB — list_hypertables, list_chunks, create_hypertable, add_compression_policy, add_retention_policy.
Exportadores de esquemas ORM — Prisma, Drizzle, SQLAlchemy, sqlc, Diesel, jOOQ, Ent, Ecto.
Flujos de eventos — subscribe_channel, poll_notifications, unsubscribe_channel, list_notification_subscriptions que conectan PostgreSQL LISTEN/NOTIFY al modelo de sondeo MCP.
Observabilidad — endpoint Prometheus /metrics + herramienta get_metrics_exposition para stdio; rastro de auditoría estructurado con redacción de credenciales basada en regex.

Documentación

docs/installation.md — instalación + configuración
docs/tour.md — recorrido guiado de herramientas
docs/cookbook.md — recetas prácticas para agentes
docs/tools.md — referencia completa de herramientas
docs/architecture.md — cómo encajan las piezas
docs/scaling.md — dimensionamiento de pools, réplicas, rendimiento
docs/security-hardening.md — hoja de ruta de funciones de seguridad
docs/release-process.md — cómo se publican las versiones en PyPI
docs/adr/ — registros de decisiones de arquitectura
Explora en https://devopam.github.io/MCPg/

Seguridad

Reporte de vulnerabilidades: consulta SECURITY.md. Ventana de divulgación coordinada de 90 días; informes a devopam@gmail.com.
Defensa en profundidad: compuertas de capacidad, kernel SafeSQL, lista blanca de identificadores, redacción de auditoría, aplicación de TLS de PG al inicio, limitación de velocidad, validación JWT OIDC, tiempos de espera por sesión.
Consulta docs/security-hardening.md para la hoja de ruta viva de elementos de endurecimiento enviados (✅) y en cola (⬜).

Política de privacidad

MCPg es autoalojado: el contenido de tu base de datos nunca sale de tu infraestructura, y no hay telemetría ni comunicación a casa de ningún tipo. La única excepción documentada es la herramienta opcional translate_nl_to_sql, que envía tu pregunta más el contexto del esquema (nombres, no datos de filas) al proveedor de LLM que tú configures. La política completa — recopilación de datos, uso, almacenamiento, intercambio con terceros, retención y contacto — está en PRIVACY.md.

Notas de versión y changelog

Consulta CHANGELOG.md para el historial completo de versiones, docs/release-process.md para saber cómo se cortan las versiones, y la página de GitHub Releases para artefactos descargables.

Contribuciones

Las pull requests son bienvenidas — consulta CONTRIBUTING.md para la configuración del bucle de desarrollo, las convenciones de prueba y la lista de verificación de revisión por PR.

Licencia

MIT — consulta LICENSE. El kernel de seguridad SQL (src/mcpg/sql/) es de primera parte, reescrito a partir del crystaldba/postgres-mcp con licencia MIT; consulta NOTICE para el linaje.

Extensiones envueltas — licencias que deberías conocer

El código fuente de MCPg es MIT, pero las extensiones de PostgreSQL que envuelve tienen cada una su propia licencia. Los wrappers en sí están a distancia (llamadas a nivel SQL, sin enlace estático o dinámico al proceso Python de MCPg), por lo que MCPg-el-proyecto no es una obra derivada de ninguna de ellas. Los operadores que despliegan un servicio construido sobre MCPg + una extensión dada asumen las obligaciones que impone la licencia de esa extensión — igual que si instalaran la extensión directamente. La matriz a continuación nombra la licencia por extensión envuelta para que puedas tomar una decisión informada.

Extensión	Licencia	Notas para operadores
pgvector	Licencia PostgreSQL (estilo BSD)	Permisiva; sin obligaciones especiales.
pg_partman	Licencia PostgreSQL	Permisiva.
pg_cron	Licencia PostgreSQL	Permisiva.
pg_turboquant	MIT	Permisiva.
pg_buffercache / pg_walinspect / pgstattuple	contrib de PostgreSQL	Permisiva.
TimescaleDB	Apache 2.0 (comunidad) + Timescale License (TSL, código disponible) para algunas funciones	Mixta — consulta la documentación de Timescale para saber qué funciones están bajo TSL.
Apache AGE	Apache 2.0	Permisiva.
pg_search (ParadeDB)	AGPL-3.0	Los operadores que ejecutan un servicio de red que permite a los usuarios interactuar con `pg_search` están sujetos a la cláusula de red de AGPL — típicamente la obligación de ofrecer el código fuente de `pg_search` (y cualquier modificación) a esos usuarios. Los wrappers de MCPg no extienden esa obligación a MCPg en sí; asumes la obligación cuando despliegas y "transmites" la extensión a través de una red. Si tu modelo de redistribución de servicios es incompatible con la cláusula de red de AGPL, elige una implementación BM25 diferente (el plan BM25 lista alternativas).

Esta matriz es un punto de partida — para la respuesta vinculante sobre tu despliegue específico, consulta el archivo LICENSE upstream de la extensión y (si importa legalmente) a tu propio asesor legal.

Aviso. Se han hecho los mejores esfuerzos para llevar MCPg a grado de producción, pero sigue siendo un proyecto en desarrollo activo y puede contener problemas. Consulta los términos de la Licencia para detalles de indemnización.

MCPg - Production-grade PostgreSQL MCP Server

Documentación

MCPg

📍 Listado en

Por qué MCPg

Instalación

Desde PyPI (recomendado)

Docker

Desde el código fuente (desarrolladores)

Inicio rápido

Instalación de un clic en Claude Desktop (.mcpb)

O conéctalo manualmente (transporte stdio)

¿Aún no tienes datos interesantes? Siembra el conjunto de datos de demostración

Ejecutar como servidor HTTP (para integraciones de IDE, aplicaciones web, etc.)

Configuración

Escenarios comunes

Referencia completa

Núcleo

Compuertas de capacidad (opt-in para herramientas de mayor radio de impacto)

Autenticación (solo transportes HTTP)

Endurecimiento HTTP (solo transportes HTTP)

Multi-tenencia (SET ROLE)

Réplicas de lectura

Múltiples bases de datos (secundarias de solo lectura)

Pool / tiempos de espera / TLS

Herramientas de subproceso (solo MCPG_ALLOW_SHELL=true)

LISTEN/NOTIFY (solo MCPG_ALLOW_LISTEN=true)

Auditoría

Backend de secretos

Limitación de tasa

Caché y banderas de características

SQL en lenguaje natural

Ejemplos de uso

Inspeccionar el esquema

Diagnosticar una consulta lenta

Traducir inglés simple a SQL

Visualiza el esquema

Audita la base de datos

Ejecuta una escritura protegida

Qué incluye

Documentación

Seguridad

Política de privacidad

Notas de versión y changelog

Contribuciones

Licencia

Extensiones envueltas — licencias que deberías conocer

Multi-tenencia (`SET ROLE`)

Herramientas de subproceso (solo `MCPG_ALLOW_SHELL=true`)

LISTEN/NOTIFY (solo `MCPG_ALLOW_LISTEN=true`)