MCPg

Un servidor de Model Context Protocol de nivel de producción para PostgreSQL. Permite a los agentes de IA inspeccionar, consultar, operar y ajustar 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 sobre datos de demostración desechables; para uso real, ejecuta MCPg junto a tu propia base de datos (consulta Inicio rápido).

📍 Listado en

• Registro oficial de MCP

• mcp.so

• mcpservers.org

• Smithery

• Glama

Por qué MCPg

• Seguro por defecto. Modo de acceso de solo lectura. Cada sentencia SQL proporcionada por el usuario se analiza a través de una lista blanca de AST validada antes de la ejecución. La interpolación de identificadores pasa por una expresión regular estricta [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 se opta por ellas. Cada herramienta publica ToolAnnotations de MCP (readOnlyHint, openWorldHint) derivadas de esas mismas compuertas, para que los clientes puedan aprobar automáticamente las lecturas y controlar las escrituras sin adivinar.

• Un solo servidor, amplia superficie. Acceso a datos de aplicación (consultas, búsqueda, cursores, NL→SQL) y operaciones de nivel DBA (comprobaciones de salud, ajuste de índices, análisis de EXPLAIN, bloqueos, vacuum, volcados, réplicas, migraciones) en un único servidor MCP. Los agentes no tienen que cambiar de herramienta para cambiar de tarea.

• Todo nativo de PostgreSQL. Sin ORM, sin impuesto de abstracción: usa psycopg3 directamente, habla con cada vista de 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.

• Con forma de producción, no de demostración. Pool de conexiones, multi-tenant por SET ROLE por solicitud, enrutamiento a 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. El endpoint Prometheus /metrics en el transporte HTTP expone mcpg_tool_calls_total{tool,status} + mcpg_tool_duration_seconds. Cada llamada a una herramienta registra un evento de auditoría estructurado con argumentos con credenciales redactadas.

• Impulsado por pruebas, multi-versió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 en el issue #120.

Related MCP server: PostgreSQL MCP Server

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 preconstruida del GitHub Container Registry (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 la \ 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 multi-etapa: la etapa de runtime 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 runtime.

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 runtime y desarrollo y expone el script de consola mcpg.

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

Inicio rápido

Instalaciones con 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 con un clic en Claude Desktop (.mcpb)

Descarga mcpg-<version>.mcpb desde el ú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 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 tiene ~2 kB y el host resuelve la versión fijada de mcpg desde PyPI para tu plataforma.

O conéctalo manualmente (transporte stdio)

Pon 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 ya 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é es lenta esta consulta? 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 un tutorial capturado, 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). Establece MCPG_HTTP_AUTH_TOKEN=... para un bearer estático, o MCPG_AUTH_MODE=oidc para validación completa de JWT contra un emisor OIDC.

Configuración

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

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 / timeouts / TLS

Herramientas de subprocesos (solo MCPG_ALLOW_SHELL=true)

LISTEN/NOTIFY (solo MCPG_ALLOW_LISTEN=true)

Auditoría

Backend de secretos

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

Limitación de velocidad

Caché y características

SQL en lenguaje natural

MCPg autodetecta automáticamente cada proveedor configurado desde el entorno al inicio — establece tantas claves de proveedor como tengas y cada una pasa a ser invocable. Hay diecinueve proveedores integrados de serie. 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 proveedor integrado es plug-and-play — establece la variable de entorno convencional de la clave de API del proveedor y se autodetecta — y cualquier otro proveedor compatible con OpenAI o servidor de modelos local (Ollama, vLLM, LM Studio) sigue siendo integrable solo mediante configuración a través de MCPG_NL2SQL_CUSTOM_PROVIDERS. Toda la lista integrada es un registro declarativo en nl2sql.py, de modo que añadir un proveedor o actualizar un modelo predeterminado retirado es un cambio de datos de una línea.

Cuando MCPG_NL2SQL_PROVIDER no está definido, MCPg elige automáticamente el predeterminado en el orden del registro — anthropic → openai → gemini siguen en primer lugar para que los despliegues existentes no se vean afectados. translate_nl_to_sql acepta un argumento opcional provider="…" para enrutar cada llamada; get_server_info informa de cuáles están configurados.

Ejemplos de uso

Las herramientas MCP son invocadas por el agente (Claude, Cursor, Continue, …) en respuesta a tus instrucciones en lenguaje natural. Algunos ejemplos ilustrativos de ida y vuelta:

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 ello antes de aplicarlo para confirmar que no hay sorpresas de bloqueo.

Traducir inglés sencillo 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 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;

Visualizar 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.

Auditar la base de datos

Tú: ¿Cómo de saludable está esta base de datos ahora mismo?

Agente (usando audit_database): Devuelve un informe con puntuaciones: 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).

Ejecutar una escritura protegida

Tú: Aplica un borrado lógico a todos los pedidos con más de 5 años.

Agente (usando run_write con MCPG_AUDIT_PERSIST=true): Valida la sentencia a través del kernel de SQL seguro, 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 vectorial + FTS, Apache AGE Cypher, TimescaleDB, exportaciones de esquemas ORM, cursores del lado del servidor — consulta docs/cookbook.md.

Qué incluye

Lista compacta por categorías. 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, disparadores, secuencias, particiones, políticas, roles, permisos, 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 mediante RRF), geo_search (PostGIS k-NN).

• Lenguaje natural → SQL — translate_nl_to_sql (22 proveedores integrados — Anthropic, OpenAI, Gemini, xAI, Groq, Mistral, Hugging Face, … — más cualquier endpoint personalizado compatible con OpenAI; la salida pasa por el mismo kernel de SQL seguro 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 de Apache AGE).

• Diff estructural y migraciones — compare_schemas, validate_migration, flujo de trabajo por etapas 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 de 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 LISTEN/NOTIFY de PostgreSQL con el modelo de sondeo de MCP.

• Observabilidad — endpoint /metrics de Prometheus + 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 por las 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 — dimensionado 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

• Notificación de vulnerabilidades: consulta SECURITY.md. Ventana de divulgación coordinada de 90 días; informes a devopam@gmail.com.

• Defensa en profundidad: puertas 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 de JWT OIDC, tiempos de espera por sesión.

• Consulta docs/security-hardening.md para la hoja de ruta viva de los elementos de endurecimiento enviados (✅) y en cola (⬜).

Política de privacidad

MCPg se aloja en tu propia infraestructura: el contenido de tu base de datos nunca sale de tu infraestructura, y no hay telemetría ni comunicación con el exterior 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 registro de cambios

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

Contribuciones

Se aceptan pull requests; consulta CONTRIBUTING.md para la configuración del bucle de desarrollo, las convenciones de pruebas 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 de crystaldba/postgres-mcp con licencia MIT; consulta NOTICE para conocer 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 envoltorios en sí están a distancia (llamadas a nivel SQL, sin enlace estático ni 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 determinada asumen las obligaciones que imponga la licencia de esa extensión, igual que si instalaran la extensión directamente. La siguiente matriz indica la licencia de cada extensión envuelta para que puedas tomar una decisión informada.

Esta matriz es un punto de partida; para la respuesta vinculante sobre tu despliegue específico, consulta el archivo LICENSE original de la extensión y, si tiene relevancia legal, a tu propio asesor.

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