MCP-PostgreSQL-Ops

MCP-PostgreSQL-Ops es un servidor MCP profesional para operaciones, monitoreo y gestión de bases de datos PostgreSQL. Compatible con PostgreSQL 12-17, ofrece análisis completo de bases de datos, monitoreo de rendimiento y recomendaciones inteligentes de mantenimiento mediante consultas en lenguaje natural.

GitHub
160
Prueba este MCPPatrocinado

Documentación

Servidor MCP para Operaciones y Monitoreo de PostgreSQL

MCP Toplist

License: MIT Python Docker Pulls PostgreSQL BuyMeACoffee

Deploy to PyPI with tag PyPI PyPI - Downloads

Arquitectura e Internos (DeepWiki)

Ask DeepWiki

Resumen

MCP-PostgreSQL-Ops es un servidor MCP profesional para operaciones, monitoreo y gestión de bases de datos PostgreSQL. Soporta PostgreSQL 12-18 con análisis integral de bases de datos, monitoreo de rendimiento y recomendaciones inteligentes de mantenimiento mediante consultas en lenguaje natural. La mayoría de las funciones funcionan de forma independiente, pero las capacidades avanzadas de análisis de consultas se mejoran cuando las extensiones pg_stat_statements y (opcionalmente) pg_stat_monitor están instaladas.

Características

  • ✅ Configuración Cero: Funciona con PostgreSQL 12-18 de fábrica con detección automática de versiones.
  • ✅ Lenguaje Natural: Haga preguntas como "Muéstrame consultas lentas" o "Analiza la fragmentación de tablas".
  • ✅ Seguro para Producción: Operaciones de solo lectura, compatible con RDS/Aurora con permisos de usuario regulares.
  • ✅ Mejorado con Extensiones: pg_stat_statements y pg_stat_monitor opcionales para análisis avanzados de consultas.
  • ✅ Monitoreo Integral de Bases de Datos: Análisis de rendimiento, detección de fragmentación y recomendaciones de mantenimiento.
  • ✅ Análisis Inteligente de Consultas: Identificación de consultas lentas con integración de pg_stat_statements y pg_stat_monitor.
  • ✅ Descubrimiento de Esquemas y Relaciones: Exploración de la estructura de la base de datos con mapeo detallado de relaciones.
  • ✅ Inteligencia de VACUUM y Autovacuum: Monitoreo de mantenimiento en tiempo real y análisis de efectividad.
  • ✅ Operaciones Multi-Base de Datos: Análisis y monitoreo fluido entre bases de datos.
  • ✅ Listo para Empresas: Operaciones seguras de solo lectura con compatibilidad con RDS/Aurora.
  • ✅ Amigable para Desarrolladores: Código base simple para fácil personalización y extensión de herramientas.

🔧 Capacidades Avanzadas

  • Estadísticas de E/S conscientes de la versión (mejoradas en PostgreSQL 16+, columnas de bytes en PG 18+).
  • Monitoreo de conexiones y bloqueos en tiempo real.
  • Análisis de procesos en segundo plano y puntos de control.
  • Estado de replicación y monitoreo de WAL.
  • Análisis de capacidad y fragmentación de bases de datos.
  • Catálogo de eventos de espera con descripciones (PG 17+).
  • Monitoreo del resumidor de WAL para copias de seguridad incrementales (PG 17+).
  • Monitoreo del subsistema de E/S asíncrono (PG 18+).
  • Estadísticas de E/S y WAL por backend (PG 18+).

Ejemplos de Uso de Herramientas

📸 Más Ejemplos con Capturas de Pantalla →

MCP-PostgreSQL-Ops Usage Screenshot

MCP-PostgreSQL-Ops Usage Screenshot

⭐ Inicio Rápido (5 minutos)

Nota: El contenedor postgresql incluido en docker-compose.yml está destinado únicamente para pruebas de inicio rápido. Puede conectarse a su propia instancia de PostgreSQL ajustando las variables de entorno según sea necesario.

Si desea usar su propia instancia de PostgreSQL en lugar del contenedor de prueba integrado:

  • Actualice la información de conexión de PostgreSQL de destino en su archivo .env (consulte POSTGRES_HOST, POSTGRES_PORT, POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB).
  • En docker-compose.yml, comente (deshabilite) los contenedores postgres y postgres-init-extensions para evitar iniciar la base de datos de prueba integrada.

Diagrama de Flujo del Inicio Rápido/Tutorial

Flow Diagram of Quickstart/Tutorial

1. Configuración del Entorno

Nota: Si bien los privilegios de superusuario brindan acceso a todas las bases de datos e información del sistema, el servidor MCP también funciona con permisos de usuario regular para tareas básicas de monitoreo.

git clone https://github.com/call518/MCP-PostgreSQL-Ops.git
cd MCP-PostgreSQL-Ops

### Check and modify .env file
cp .env.example .env
vim .env

### No need to modify defaults, but if using your own PostgreSQL server, edit below:
POSTGRES_HOST=host.docker.internal
POSTGRES_PORT=15432  # External port for host access (mapped to internal 5432)
POSTGRES_USER=postgres
POSTGRES_PASSWORD=changeme!@34
POSTGRES_DB=ecommerce # Default connection DB. Superusers can access all DBs.

Nota: PGDATA=/data/db está preconfigurado para la imagen Docker de Percona PostgreSQL, que requiere esta ruta específica para permisos de escritura adecuados.

2. Iniciar Contenedores de Demostración

# Start all containers including built-in PostgreSQL for testing
docker-compose up -d

# Alternative: If using your own PostgreSQL instance
# Comment out postgres and postgres-init-extensions services in docker-compose.yml
# Then use the custom configuration:
# docker-compose -f docker-compose.custom-db.yml up -d

⏰ Espere la Configuración del Entorno: La configuración inicial del entorno toma unos minutos ya que los contenedores se inician en secuencia:

  1. El contenedor de PostgreSQL se inicia primero con la inicialización de la base de datos
  2. El contenedor de Extensiones de PostgreSQL instala extensiones y crea datos de prueba integrales (~83K registros)
  3. Los contenedores del Servidor MCP y del Proxy MCPO se inician después de que PostgreSQL esté listo
  4. El contenedor de OpenWebUI se inicia al final y puede tardar más tiempo en cargar la interfaz web

💡 Consejo: Espere 2-3 minutos después de ejecutar docker-compose up -d antes de acceder a OpenWebUI para asegurarse de que todos los servicios estén completamente inicializados.

🔍 Verificar Estado de los Contenedores (Opcional):

# Monitor container startup progress
docker-compose logs -f

# Check if all containers are running
docker-compose ps

# Verify PostgreSQL is ready
docker-compose logs postgres | grep "ready to accept connections"

3. Acceso a OpenWebUI

http://localhost:3003/

  • La lista de funciones de herramientas MCP proporcionadas por swagger se puede encontrar en la URL de Documentación de la API de MCPO.
    • ej.: http://localhost:8003/docs

4. Registro de la Herramienta en OpenWebUI

📌 Nota: Las instrucciones de configuración de la interfaz web se basan en OpenWebUI v0.6.22. Las ubicaciones de los menús y la configuración pueden diferir en versiones más nuevas.

  1. Inicie sesión en OpenWebUI con una cuenta de administrador
  2. Vaya a "Configuración" → "Herramientas" desde el menú superior.
  3. Ingrese la dirección de la Herramienta postgresql-ops (ej., http://localhost:8003/postgresql-ops) para conectar las Herramientas MCP.
  4. Configure Ollama u OpenAI.

5. ¡Completado!

¡Felicitaciones! Su servidor de operaciones MCP PostgreSQL está ahora listo para usar. Puede comenzar a explorar sus bases de datos con consultas en lenguaje natural.

🚀 Pruebe Estas Consultas de Ejemplo:

  • "Muéstrame las conexiones activas actuales"
  • "¿Cuáles son las consultas más lentas del sistema?"
  • "Analiza la fragmentación de tablas en todas las bases de datos"
  • "Muéstrame información del tamaño de la base de datos"
  • "¿Qué tablas necesitan mantenimiento de VACUUM?"

📖 Próximos Pasos:

(NOTA) Resumen de Datos de Prueba de Muestra

El script create-test-data.sql es ejecutado por el contenedor postgres-init-extensions (definido en docker-compose.yml) en el primer inicio, generando automáticamente bases de datos de prueba integrales para probar las herramientas MCP:

Base de DatosPropósitoEsquema y TablasEscala
ecommerceSistema de comercio electrónicopublic: categories, products, customers, orders, order_items10 categorías, 500 productos, 100 clientes, 200 pedidos, 400 artículos de pedido
analyticsAnálisis e informespublic: page_views, sales_summary1,000 vistas de página, 30 resúmenes de ventas
inventoryGestión de almacénpublic: suppliers, inventory_items, purchase_orders10 proveedores, 100 artículos, 50 órdenes de compra
hr_systemGestión de RR.HH.public: departments, employees, payroll5 departamentos, 50 empleados, 150 registros de nómina

Usuarios de prueba creados: app_readonly, app_readwrite, analytics_user, backup_user

Optimizado para pruebas: Fragmentación intencional de tablas, varios índices (usados/no usados), datos de series temporales, relaciones complejas

Matriz de Compatibilidad de Herramientas

Adaptación Automática: Todas las herramientas funcionan de forma transparente en las versiones compatibles: ¡no se necesita configuración!

🟢 Herramientas Independientes de Extensiones (No Se Requieren Extensiones)

Nombre de la HerramientaExtensiones RequeridasPG 12PG 13PG 14PG 15PG 16PG 17PG 18Vistas/Tablas del Sistema Utilizadas
get_server_info❌ Ninguna✅✅✅✅✅✅✅version(), pg_extension
get_active_connections❌ Ninguna✅✅✅✅✅✅✅pg_stat_activity
get_postgresql_config❌ Ninguna✅✅✅✅✅✅✅pg_settings
get_database_list❌ Ninguna✅✅✅✅✅✅✅pg_database
get_table_list❌ Ninguna✅✅✅✅✅✅✅information_schema.tables
get_table_schema_info❌ Ninguna✅✅✅✅✅✅✅information_schema.*, pg_indexes
get_database_schema_info❌ Ninguna✅✅✅✅✅✅✅pg_namespace, pg_class, pg_proc
get_table_relationships❌ Ninguna✅✅✅✅✅✅✅information_schema.* (restricciones)
get_user_list❌ Ninguna✅✅✅✅✅✅✅pg_user, pg_roles
get_index_usage_stats❌ Ninguna✅✅✅✅✅✅✅pg_stat_user_indexes
get_database_size_info❌ Ninguna✅✅✅✅✅✅✅pg_database_size()
get_table_size_info❌ Ninguna✅✅✅✅✅✅✅pg_total_relation_size()
get_vacuum_analyze_stats❌ Ninguna✅✅✅✅✅✅✅ Mejoradapg_stat_user_tables
get_current_database_info❌ Ninguna✅✅✅✅✅✅✅pg_database, current_database()
get_table_bloat_analysis❌ Ninguna✅✅✅✅✅✅✅pg_stat_user_tables
get_database_bloat_overview❌ Ninguna✅✅✅✅✅✅✅pg_stat_user_tables
get_autovacuum_status❌ Ninguna✅✅✅✅✅✅✅pg_stat_user_tables
get_autovacuum_activity❌ Ninguna✅✅✅✅✅✅✅pg_stat_user_tables
get_running_vacuum_operations❌ Ninguna✅✅✅✅✅✅✅pg_stat_activity
get_vacuum_effectiveness_analysis❌ Ninguna✅✅✅✅✅✅✅pg_stat_user_tables
get_lock_monitoring❌ Ninguna✅✅✅✅✅✅✅pg_locks, pg_stat_activity
get_wal_status❌ Ninguna✅✅✅✅✅✅✅pg_current_wal_lsn()
get_database_stats❌ Ninguna✅✅✅✅✅✅✅ Mejoradapg_stat_database
get_table_io_stats❌ Ninguna✅✅✅✅✅✅✅pg_statio_user_tables
get_index_io_stats❌ Ninguna✅✅✅✅✅✅✅pg_statio_user_indexes
get_database_conflicts_stats❌ Ninguna✅✅✅✅✅✅✅pg_stat_database_conflicts

🚀 Herramientas Conscientes de la Versión (Auto-Adaptables)

Nombre de la HerramientaExtensiones RequeridasPG 12PG 13PG 14PG 15PG 16PG 17PG 18Características Especiales
get_io_stats❌ Ninguna✅ Básico✅ Básico✅ Básico✅ Básico✅ Mejorado✅ Mejorado✅ MejoradoPG16+: soporte de pg_stat_io; PG18+: columnas de bytes
get_bgwriter_stats❌ Ninguna✅✅✅✅✅✅ Especial✅ MejoradoPG17: Estadísticas de checkpointer separadas; PG18+: num_done, slru_written
get_replication_status❌ Ninguna✅ Compatible✅ Mejorado✅ Mejorado✅ Mejorado✅ Mejorado✅ Mejorado✅ MejoradoPG13+: wal_status, safe_wal_size; PG16+: receptor WAL mejorado; PG17+: invalidation_reason, inactive_since
get_all_tables_stats❌ Ninguna✅ Compatible✅ Mejorado✅ Mejorado✅ Mejorado✅ Mejorado✅ Mejorado✅ MejoradoPG13+: seguimiento de n_ins_since_vacuum para optimización del mantenimiento de vacuum
get_user_functions_stats⚙️ Configuración Requerida✅✅✅✅✅✅✅Requiere track_functions=pl
get_wait_events❌ Ninguna✅ Respaldo✅ Respaldo✅ Respaldo✅ Respaldo✅ Respaldo✅ Nativo✅ NativoPG17+: catálogo pg_wait_events; PG12-16: respaldo a esperas actuales de pg_stat_activity
get_wal_summarizer_status❌ Ninguna❌❌❌❌❌✅✅PG17+: monitoreo del resumidor de WAL para copias de seguridad incrementales
get_async_io_status❌ Ninguna❌❌❌❌❌❌✅PG18+: monitoreo del subsistema de E/S asíncrono pg_aios
get_per_backend_io_stats❌ Ninguna❌❌❌❌❌❌✅PG18+: estadísticas de E/S y WAL por backend

🟡 Herramientas Dependientes de Extensiones (Se Requieren Extensiones)

Nombre de la herramientaExtensión requeridaPG 12PG 13PG 14PG 15PG 16PG 17PG 18Notas
get_pg_stat_statements_top_queriespg_stat_statements✅ Compatible✅ Mejorado✅ Mejorado✅ Mejorado✅ Mejorado✅ Mejorado✅ MejoradoPG12: total_time → total_exec_time; PG13+: nativo total_exec_time; PG17+: stats_since
get_pg_stat_monitor_recent_queriespg_stat_monitor✅ Compatible✅ Mejorado✅ Mejorado✅ Mejorado✅ Mejorado✅ Mejorado✅ MejoradoPG12: total_time → total_exec_time; PG13+: nativo total_exec_time

🆕 Características específicas de la versión

PostgreSQL 17

  • pg_wait_events vista: Catálogo nativo de eventos de espera con descripciones (usado por get_wait_events)
  • Resumidor WAL: Monitoreo para soporte de copias de seguridad incrementales (usado por get_wal_summarizer_status)
  • Mejoras en los slots de replicación: columnas invalidation_reason y inactive_since (usado por get_replication_status)
  • pg_stat_statements stats_since: Rastrear cuándo se restablecieron las estadísticas por última vez (usado por get_pg_stat_statements_top_queries)
  • Progreso de VACUUM: Seguimiento de vaciado de índices en vistas de progreso (mejora futura para get_running_vacuum_operations)

PostgreSQL 18

  • pg_aios vista: Monitoreo del subsistema de E/S asíncrona (usado por get_async_io_status)
  • Estadísticas de E/S por backend: Estadísticas de E/S y WAL por backend individual (usado por get_per_backend_io_stats)
  • Columnas de tiempo de VACUUM/ANALYZE: total_vacuum_time, total_autovacuum_time, total_analyze_time, total_autoanalyze_time tiempo acumulado (usado por get_vacuum_analyze_stats)
  • Columnas de bytes pg_stat_io: read_bytes, write_bytes, extend_bytes (usado por get_io_stats)
  • Estadísticas de trabajadores paralelos: parallel_workers_launched, parallel_workers_to_launch (usado por get_database_stats)
  • Mejoras en el checkpoint: columnas num_done, slru_written (usado por get_bgwriter_stats)

Ejemplos de uso

Integración con Claude Desktop

(Recomendado) Añade a tu archivo de configuración de Claude Desktop:

{
  "mcpServers": {
    "mcp-postgresql-ops": {
      "command": "uvx",
      "args": ["--python", "3.12", "mcp-postgresql-ops"],
      "env": {
        "POSTGRES_HOST": "127.0.0.1",
        "POSTGRES_PORT": "15432",
        "POSTGRES_USER": "postgres",
        "POSTGRES_PASSWORD": "changeme!@34",
        "POSTGRES_DB": "ecommerce"
      }
    }
  }
}

"Muestra todas las conexiones activas en un formato de tabla HTML claro y legible." Claude Desktop Integration

"Muestra todas las relaciones para la tabla de clientes en la base de datos de comercio electrónico como un diagrama de Mermaid." Claude Desktop Integration

Instalación

Desde PyPI (Recomendado)

# Install the package
pip install mcp-postgresql-ops

# Or with uv (faster)
uv add mcp-postgresql-ops

# Verify installation
mcp-postgresql-ops --help

Desde el código fuente

# Clone the repository
git clone https://github.com/call518/MCP-PostgreSQL-Ops.git
cd MCP-PostgreSQL-Ops

# Install with uv (recommended)
uv sync
uv run mcp-postgresql-ops --help

# Or with pip
pip install -e .
mcp-postgresql-ops --help

Configuración de MCP

Configuración de Claude Desktop

(Opcional) Ejecutar con código fuente local:

{
  "mcpServers": {
    "mcp-postgresql-ops": {
      "command": "uv",
      "args": ["run", "python", "-m", "mcp_postgresql_ops"],
      "env": {
        "POSTGRES_HOST": "127.0.0.1",
        "POSTGRES_PORT": "15432",
        "POSTGRES_USER": "postgres",
        "POSTGRES_PASSWORD": "changeme!@34",
        "POSTGRES_DB": "ecommerce"
      }
    }
  }
}

Ejecutar MCP-Server como independiente

Con PyPI y uvx (Recomendado)

# Stdio mode
uvx --python 3.12 mcp-postgresql-ops \
  --type stdio

# HTTP mode
uvx --python 3.12 mcp-postgresql-ops
  --type streamable-http \
  --host 127.0.0.1 \
  --port 8000 \
  --log-level DEBUG

(Opción) Configurar múltiples instancias de PostgreSQL

{
  "mcpServers": {
    "Postgresql-A": {
      "command": "uvx",
      "args": ["--python", "3.12", "mcp-postgresql-ops"],
      "env": {
        "POSTGRES_HOST": "a.foo.com",
        "POSTGRES_PORT": "5432",
        "POSTGRES_USER": "postgres",
        "POSTGRES_PASSWORD": "postgres",
        "POSTGRES_DB": "postgres"
      }
    },
    "Postgresql-B": {
      "command": "uvx",
      "args": ["--python", "3.12", "mcp-postgresql-ops"],
      "env": {
        "POSTGRES_HOST": "b.bar.com",
        "POSTGRES_PORT": "5432",
        "POSTGRES_USER": "postgres",
        "POSTGRES_PASSWORD": "postgres",
        "POSTGRES_DB": "postgres"
      }
    }
  }
}

Con código fuente local

# Method 1: Module execution (for development, requires PYTHONPATH)
PYTHONPATH=/path/to/MCP-PostgreSQL-Ops/src
python -m mcp_postgresql_ops \
  --type stdio

# Method 2: Direct script (after uv installation in project directory)
uv run mcp-postgresql-ops \
  --type stdio

# Method 3: Installed package script (after pip/uv install)
mcp-postgresql-ops \
  --type stdio

# HTTP mode examples:
# Development mode
PYTHONPATH=/path/to/MCP-PostgreSQL-Ops/src
python -m mcp_postgresql_ops \
  --type streamable-http \
  --host 127.0.0.1 \
  --port 8000 \
  --log-level DEBUG

# Production mode (after installation)
mcp-postgresql-ops \
  --type streamable-http \
  --host 127.0.0.1 \
  --port 8000 \
  --log-level DEBUG

Argumentos de CLI

  • --type: Tipo de transporte (stdio o streamable-http) - Predeterminado: stdio
  • --host: Dirección del host para transporte HTTP - Predeterminado: 127.0.0.1
  • --port: Número de puerto para transporte HTTP - Predeterminado: 8000
  • --auth-enable: Habilitar autenticación con token Bearer para el modo streamable-http - Predeterminado: false
  • --secret-key: Clave secreta para autenticación con token Bearer (requerida cuando la autenticación está habilitada)
  • --log-level: Nivel de registro (DEBUG, INFO, WARNING, ERROR, CRITICAL) - Predeterminado: INFO

Variables de entorno

VariableDescripciónPredeterminadoPredeterminado del proyecto
PYTHONPATHRuta de búsqueda de módulos de Python (solo necesario para modo de desarrollo)-/app/src
MCP_LOG_LEVELVerbosidad del registro del servidor (DEBUG, INFO, WARNING, ERROR)INFOINFO
FASTMCP_TYPEProtocolo de transporte MCP (stdio para CLI, streamable-http para web)stdiostreamable-http
FASTMCP_HOSTDirección de enlace del servidor HTTP (0.0.0.0 para todas las interfaces)127.0.0.10.0.0.0
FASTMCP_PORTPuerto del servidor HTTP para comunicación MCP80008000
REMOTE_AUTH_ENABLEHabilitar autenticación con token Bearer para modo streamable-http (Predeterminado: false si no está definido/nulo/vacío)falsefalse
REMOTE_SECRET_KEYClave secreta para autenticación con token Bearer (requerida cuando la autenticación está habilitada)-your-secret-key-here
PGSQL_VERSIONVersión principal de PostgreSQL para selección de imagen Docker1717
PGDATADirectorio de datos de PostgreSQL dentro del contenedor Docker (No modificar)/var/lib/postgresql/data/data/db
POSTGRES_HOSTNombre de host o dirección IP del servidor PostgreSQL127.0.0.1host.docker.internal
POSTGRES_PORTNúmero de puerto del servidor PostgreSQL543215432
POSTGRES_USERNombre de usuario de conexión a PostgreSQL (necesita permisos de lectura)postgrespostgres
POSTGRES_PASSWORDContraseña del usuario de PostgreSQL (soporta caracteres especiales)changeme!@34changeme!@34
POSTGRES_DBNombre de base de datos predeterminado para conexionestestdbecommerce
POSTGRES_MAX_CONNECTIONSParámetro de configuración max_connections de PostgreSQL200200
DOCKER_EXTERNAL_PORT_OPENWEBUIMapeo de puerto del host para contenedor Open WebUI80803003
DOCKER_EXTERNAL_PORT_MCP_SERVERMapeo de puerto del host para contenedor del servidor MCP808018003
DOCKER_EXTERNAL_PORT_MCPO_PROXYMapeo de puerto del host para contenedor proxy MCPO80008003
DOCKER_INTERNAL_PORT_POSTGRESQLPuerto interno del contenedor PostgreSQL54325432

Nota: POSTGRES_DB sirve como base de datos objetivo predeterminada para operaciones cuando no se especifica una base de datos específica. En entornos Docker, si se establece un nombre no predeterminado, esta base de datos se creará automáticamente durante el inicio inicial de PostgreSQL.

Configuración de puerto: El contenedor PostgreSQL integrado utiliza el mapeo de puertos 15432:5432 donde:

  • POSTGRES_PORT=15432: Puerto externo para acceso desde el host y conexiones del servidor MCP
  • DOCKER_INTERNAL_PORT_POSTGRESQL=5432: Puerto interno del contenedor (predeterminado de PostgreSQL)
  • Cuando se utilizan servidores PostgreSQL externos, establece POSTGRES_PORT para que coincida con el puerto real de tu servidor

Requisitos previos

Extensiones PostgreSQL requeridas

Para más detalles, consulta la ## Matriz de compatibilidad de herramientas

Nota: La mayoría de las herramientas MCP funcionan sin extensiones de PostgreSQL. La sección a continuación. Algunas herramientas avanzadas de análisis de rendimiento requieren las siguientes extensiones:

-- Query performance statistics (required only for get_pg_stat_statements_top_queries)
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

-- Advanced monitoring (optional, used by get_pg_stat_monitor_recent_queries)
CREATE EXTENSION IF NOT EXISTS pg_stat_monitor;

Configuración rápida: Para instalaciones nuevas de PostgreSQL, añade a postgresql.conf:

shared_preload_libraries = 'pg_stat_statements'

Luego reinicia PostgreSQL y ejecuta los comandos CREATE EXTENSION anteriores.

  • pg_stat_statements es requerido solo para herramientas de análisis de consultas lentas.
  • pg_stat_monitor es opcional y se utiliza para monitoreo de consultas en tiempo real.
  • Todas las demás herramientas funcionan sin estas extensiones.

Requisitos mínimos

  • PostgreSQL 12+ (probado con PostgreSQL 17 y 18)
  • Python 3.12
  • Acceso de red al servidor PostgreSQL
  • Permisos de lectura en los catálogos del sistema

Configuración requerida de PostgreSQL

⚠️ Configuración de recopilación de estadísticas: Algunas herramientas MCP requieren parámetros de configuración específicos de PostgreSQL para recopilar estadísticas. Elige uno de los siguientes métodos de configuración:

Herramientas afectadas por esta configuración:

  • get_user_functions_stats: Requiere track_functions = pl o track_functions = all
  • get_table_io_stats y get_index_io_stats: Sincronización más precisa con track_io_timing = on
  • get_database_stats: Sincronización de E/S mejorada con track_io_timing = on

Verificación: Después de aplicar cualquier método, verifica la configuración:

SELECT name, setting, context FROM pg_settings WHERE name IN ('track_activities', 'track_counts', 'track_io_timing', 'track_functions') ORDER BY name;

       name       | setting |  context  
------------------+---------+-----------
 track_activities | on      | superuser
 track_counts     | on      | superuser
 track_functions  | pl      | superuser
 track_io_timing  | on      | superuser
(4 rows)

Método 1: postgresql.conf (Recomendado para PostgreSQL autogestionado)

Añade lo siguiente a tu postgresql.conf:

# Basic statistics collection (usually enabled by default)
track_activities = on
track_counts = on

# Required for function statistics tools
track_functions = pl    # Enables PL/pgSQL function statistics collection

# Optional but recommended for accurate I/O timing
track_io_timing = on    # Enables I/O timing statistics collection

Luego reinicia el servidor PostgreSQL.

Método 2: Parámetros de inicio de PostgreSQL

Para Docker o inicio de PostgreSQL desde línea de comandos:

# Docker example
docker run -d \
  -e POSTGRES_PASSWORD=mypassword \
  postgres:17 \
  -c track_activities=on \
  -c track_counts=on \
  -c track_functions=pl \
  -c track_io_timing=on

# Direct postgres command
postgres -D /data \
  -c track_activities=on \
  -c track_counts=on \
  -c track_functions=pl \
  -c track_io_timing=on

Método 3: Configuración dinámica (AWS RDS, Azure, GCP, Servicios gestionados)

Para servicios PostgreSQL gestionados donde no puedes modificar postgresql.conf, usa comandos SQL para cambiar la configuración dinámicamente:

-- Enable basic statistics collection (usually enabled by default)
ALTER SYSTEM SET track_activities = 'on';
ALTER SYSTEM SET track_counts = 'on';

-- Enable function statistics collection (requires superuser privileges)
ALTER SYSTEM SET track_functions = 'pl';

-- Enable I/O timing statistics (optional but recommended)
ALTER SYSTEM SET track_io_timing = 'on';

-- Reload configuration without restart (run separately)
SELECT pg_reload_conf();

Alternativa para pruebas a nivel de sesión:

-- Set for current session only (temporary)
SET track_activities = 'on';
SET track_counts = 'on';
SET track_functions = 'pl';
SET track_io_timing = 'on';

Nota: Cuando uses herramientas de línea de comandos, ejecuta cada sentencia SQL por separado para evitar errores de bloqueo de transacción.

Compatibilidad con RDS/Aurora

  • Este servidor es de solo lectura y funciona con roles regulares en RDS/Aurora. Para análisis avanzados, habilita pg_stat_statements; pg_stat_monitor no está disponible en motores gestionados.
  • En RDS/Aurora, prefiere el Grupo de Parámetros de BD sobre ALTER SYSTEM para configuraciones persistentes. 
    -- Verify preload setting
SHOW shared_preload_libraries;

-- Enable extension in target DB
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

-- Recommended visibility for monitoring
GRANT pg_read_all_stats TO <app_user>;

Ejemplos de consultas

🟢 Herramientas independientes de extensiones (Siempre disponibles)

  • get_server_info
    • "Mostrar la versión del servidor PostgreSQL y el estado de las extensiones."
    • "Comprobar si pg_stat_statements está instalado."
  • get_active_connections
    • "Mostrar todas las conexiones activas."
    • "Listar las sesiones actuales con base de datos y usuario."
  • get_postgresql_config
    • "Mostrar todos los parámetros de configuración de PostgreSQL."
    • "Encontrar todos los ajustes de configuración relacionados con memoria."
  • get_database_list
    • "Listar todas las bases de datos y sus tamaños."
    • "Mostrar la lista de bases de datos con información del propietario."
  • get_table_list
    • "Listar todas las tablas en la base de datos ecommerce."
    • "Mostrar los tamaños de las tablas en el esquema public."
  • get_table_schema_info
    • "Mostrar información detallada del esquema para la tabla customers en la base de datos ecommerce."
    • "Obtener detalles de columnas y restricciones para la tabla products en la base de datos ecommerce."
    • "Analizar la estructura de la tabla con índices y claves foráneas para la tabla orders en el esquema sales de la base de datos ecommerce."
    • "Mostrar una visión general del esquema para todas las tablas en el esquema public de la base de datos inventory."
    • 📋 Características: Tipos de columna, restricciones, índices, claves foráneas, metadatos de tabla
    • ⚠️ Requerido: El parámetro database_name debe especificarse
  • get_database_schema_info
    • "Mostrar todos los esquemas en la base de datos ecommerce con su contenido."
    • "Obtener información detallada sobre el esquema sales en la base de datos ecommerce."
    • "Analizar la estructura del esquema y los permisos para la base de datos inventory."
    • "Mostrar una visión general del esquema con recuentos de tablas y tamaños para la base de datos hr_system."
    • 📋 Características: Propietarios de esquemas, permisos, recuentos de objetos, tamaños, contenido
    • ⚠️ Requerido: El parámetro database_name debe especificarse
  • get_table_relationships
    • "Mostrar todas las relaciones para la tabla customers en la base de datos ecommerce."
    • "Analizar las relaciones de claves foráneas para la tabla orders en el esquema sales de la base de datos ecommerce."
    • "Obtener una visión general de relaciones en toda la base de datos ecommerce."
    • "Encontrar todas las tablas que referencian la tabla products en la base de datos ecommerce."
    • "Mostrar relaciones entre esquemas en la base de datos inventory."
    • 📋 Características: Relaciones de claves foráneas (entrantes/salientes), dependencias entre esquemas, detalles de restricciones
    • ⚠️ Requerido: El parámetro database_name debe especificarse
    • 💡 Uso: Deje table_name vacío para el análisis de relaciones en toda la base de datos
  • get_user_list
    • "Listar todos los usuarios de la base de datos y sus roles."
    • "Mostrar los permisos de usuario para una base de datos específica."
  • get_index_usage_stats
    • "Analizar la eficiencia del uso de índices."
    • "Encontrar índices no utilizados en la base de datos actual."
  • get_database_size_info
    • "Mostrar el análisis de capacidad de la base de datos."
    • "Encontrar las bases de datos más grandes por tamaño."
  • get_table_size_info
    • "Mostrar el análisis de tamaño de tablas e índices."
    • "Encontrar las tablas más grandes en un esquema específico."
  • get_vacuum_analyze_stats
    • "Mostrar operaciones recientes de VACUUM y ANALYZE."
    • "Listar tablas que necesitan VACUUM."
  • get_current_database_info
    • "¿A qué base de datos estoy conectado?"
    • "Mostrar información de la base de datos actual y detalles de conexión."
    • "Mostrar codificación, collation y tamaño de la base de datos."
    • 📋 Características: Nombre de la base de datos, codificación, collation, tamaño, límites de conexión
    • 🔧 PostgreSQL 12-18: Totalmente compatible, no requiere extensiones
  • get_table_bloat_analysis
    • "Analizar el bloat de tablas en la base de datos actual."
    • "Mostrar proporciones de tuplas muertas y estimaciones de bloat para el patrón de la tabla user_logs."
    • "Encontrar tablas con alto bloat que necesitan mantenimiento VACUUM."
    • "Analizar bloat en un esquema específico con un mínimo de 100 tuplas muertas."
    • 📋 Características: Proporciones de tuplas muertas, estimaciones de tamaño de bloat, recomendaciones de VACUUM, filtrado por patrón
    • 🔧 PostgreSQL 12-18: Totalmente compatible, no requiere extensiones
    • 💡 Uso: Enfoque independiente de extensiones usando pg_stat_user_tables
  • get_database_bloat_overview
    • "Mostrar resumen de bloat en toda la base de datos por esquema."
    • "Obtener una vista de alto nivel de la eficiencia de almacenamiento en todos los esquemas."
    • "Identificar esquemas que requieren atención de mantenimiento."
    • 📋 Características: Agregación a nivel de esquema, estimaciones totales de bloat, estado de mantenimiento
    • 🔧 PostgreSQL 12-18: Totalmente compatible, no requiere extensiones
  • get_autovacuum_status
    • "Comprobar la configuración de autovacuum y las condiciones de activación."
    • "Mostrar tablas que necesitan atención inmediata de autovacuum."
    • "Analizar los porcentajes de umbral de autovacuum para el esquema public."
    • "Encontrar tablas que se acercan a los puntos de activación de autovacuum."
    • 📋 Características: Análisis de umbrales de activación, clasificación de urgencia, estado de configuración
    • 🔧 PostgreSQL 12-18: Totalmente compatible, no requiere extensiones
    • 💡 Uso: Monitoreo de autovacuum independiente de extensiones usando pg_stat_user_tables
  • get_autovacuum_activity
    • "Mostrar patrones de actividad de autovacuum de las últimas 48 horas."
    • "Monitorear la frecuencia y el momento de ejecución de autovacuum."
    • "Encontrar tablas con patrones irregulares de autovacuum."
    • "Analizar el historial reciente de autovacuum y autoanalyze."
    • 📋 Características: Patrones de actividad, frecuencia de ejecución, análisis de tiempos
    • 🔧 PostgreSQL 12-18: Totalmente compatible, no requiere extensiones
    • 💡 Uso: Análisis histórico de patrones de autovacuum
  • get_running_vacuum_operations
    • "Mostrar operaciones VACUUM y ANALYZE actualmente en ejecución."
    • "Monitorear operaciones de mantenimiento activas y su progreso."
    • "Comprobar si alguna operación VACUUM está bloqueando consultas."
    • "Encontrar operaciones de mantenimiento de larga duración."
    • 📋 Características: Estado de operaciones en tiempo real, tiempo transcurrido, nivel de impacto, detalles del proceso
    • 🔧 PostgreSQL 12-18: Totalmente compatible, no requiere extensiones
    • 💡 Uso: Monitoreo de mantenimiento en tiempo real usando pg_stat_activity
  • get_vacuum_effectiveness_analysis
    • "Analizar la efectividad de VACUUM y los patrones de mantenimiento."
    • "Comparar la eficiencia de VACUUM manual vs autovacuum."
    • "Encontrar tablas con patrones de mantenimiento subóptimos."
    • "Comprobar la frecuencia de VACUUM frente a las proporciones de actividad de tablas."
    • 📋 Características: Análisis de patrones de mantenimiento, evaluación de efectividad, proporciones DML-a-VACUUM
    • 🔧 PostgreSQL 12-18: Totalmente compatible, no requiere extensiones
    • 💡 Uso: Análisis estratégico de VACUUM usando estadísticas existentes
  • get_lock_monitoring
    • "Mostrar todos los bloqueos actuales y sesiones bloqueadas."
    • "Mostrar solo sesiones bloqueadas con el filtro granted=false."
    • "Monitorear bloqueos por usuario específico con filtro de nombre de usuario."
    • "Comprobar bloqueos exclusivos con filtro de modo."
  • get_wal_status
    • "Mostrar el estado de WAL e información de archivado."
    • "Monitorear la generación de WAL y la posición actual de LSN."
  • get_replication_status
    • "Comprobar conexiones de replicación y estado de retraso."
    • "Monitorear slots de replicación y estado del receptor WAL."
  • get_database_stats
    • "Mostrar métricas completas de rendimiento de la base de datos."
    • "Analizar proporciones de confirmación de transacciones y estadísticas de E/S."
    • "Monitorear proporciones de aciertos de caché de búfer y uso de archivos temporales."
  • get_bgwriter_stats
    • "Analizar el rendimiento y la sincronización de checkpoints."
    • "Mostrar el rendimiento de checkpoints."
    • "Mostrar estadísticas de eficiencia del escritor en segundo plano."
    • "Monitorear la asignación de búferes y los patrones de fsync."
  • get_user_functions_stats
    • "Analizar el rendimiento de funciones definidas por el usuario."
    • "Mostrar recuentos de llamadas a funciones y tiempos de ejecución."
    • "Identificar cuellos de botella de rendimiento en funciones personalizadas."
    • ⚠️ Requiere: track_functions = pl en postgresql.conf
  • get_table_io_stats
    • "Analizar el rendimiento de E/S de tablas y las proporciones de aciertos de búfer."
    • "Identificar tablas con mal rendimiento de caché de búfer."
    • "Monitorear estadísticas de E/S de tablas TOAST."
    • 💡 Mejorado con: track_io_timing = on para tiempos precisos
  • get_index_io_stats
    • "Mostrar el rendimiento de E/S de índices y la eficiencia de búfer."
    • "Identificar índices que causan E/S de disco excesiva."
    • "Monitorear patrones de amigabilidad de caché de índices."
    • 💡 Mejorado con: track_io_timing = on para tiempos precisos
  • get_database_conflicts_stats
    • "Comprobar conflictos de replicación en servidores en espera."
    • "Analizar tipos de conflicto y estadísticas de resolución."
    • "Monitorear patrones de cancelación de consultas en servidores en espera."
    • "Monitorear la generación de WAL y la posición actual de LSN."
  • get_replication_status
    • "Comprobar conexiones de replicación y estado de retraso."
    • "Monitorear slots de replicación y estado del receptor WAL."

🚀 Herramientas Conscientes de Versión (Auto-Adaptables)

  • get_io_stats (¡Nuevo!)
    • "Mostrar estadísticas completas de E/S." (PostgreSQL 16+ proporciona desglose detallado)
    • "Analizar estadísticas de E/S."
    • "Analizar la eficiencia de la caché de búfer y los tiempos de E/S."
    • "Monitorear patrones de E/S por tipo de backend y contexto."
    • 📈 PG16+: pg_stat_io completo con tiempos, tipos de backend y contextos
    • 📊 PG12-15: Recurso alternativo básico pg_statio_* con proporciones de aciertos de búfer
  • get_bgwriter_stats (¡Mejorado!)
    • "Mostrar el rendimiento del escritor en segundo plano y de checkpoints."
    • 📈 PG17+: Estadísticas separadas de checkpointer y bgwriter mediante pg_stat_checkpointer
    • 📊 PG12-16: Estadísticas combinadas de bgwriter (incluye datos de checkpointer)
  • get_server_info (¡Mejorado!)
    • "Mostrar la versión del servidor y las características de compatibilidad."
    • "Comprobar la compatibilidad del servidor."
    • "Comprobar qué herramientas MCP están disponibles en esta versión de PostgreSQL."
    • "Muestra la matriz de disponibilidad de características y recomendaciones de actualización."
  • get_all_tables_stats (¡Mejorado!)
    • "Mostrar estadísticas completas para todas las tablas." (compatible con versiones PG12-18)
    • "Incluir tablas del sistema con el parámetro include_system=true."
    • "Analizar patrones de acceso a tablas y necesidades de mantenimiento."
    • 📈 PG13+: Rastrea inserciones desde vacuum (n_ins_since_vacuum) para una programación óptima de mantenimiento
    • 📊 PG12: Modo compatible con NULL para columnas no soportadas
  • get_wait_events (¡Nuevo!)
    • "Mostrar tipos de eventos de espera y descripciones."
    • "¿Qué eventos de espera están disponibles en esta versión de PostgreSQL?"
    • 📈 PG17+: Catálogo nativo pg_wait_events con descripciones completas
    • 📊 PG12-16: Recurso alternativo a pg_stat_activity esperas actuales agrupadas por tipo
  • get_wal_summarizer_status (¡Nuevo! PG 17+)
    • "Mostrar el estado del resumidor WAL para copias de seguridad incrementales."
    • "Monitorear el progreso de resumen de WAL."
    • 📈 PG17+: Monitoreo del resumidor WAL mediante pg_get_wal_summarizer_state()
    • ❌ PG12-16: No disponible (devuelve mensaje informativo)
  • get_async_io_status (¡Nuevo! PG 18+)
    • "Mostrar el estado del subsistema de E/S asíncrona."
    • "Monitorear pg_aios para operaciones de E/S asíncrona."
    • 📈 PG18+: Vista pg_aios para monitoreo de E/S asíncrona
    • ❌ PG12-17: No disponible (devuelve mensaje informativo)
  • get_per_backend_io_stats (¡Nuevo! PG 18+)
    • "Mostrar estadísticas de E/S y WAL por backend."
    • "Analizar patrones de E/S por proceso backend individual."
    • 📈 PG18+: Estadísticas de E/S por backend con estadísticas WAL
    • ❌ PG12-17: No disponible (devuelve mensaje informativo)

🟡 Herramientas Dependientes de Extensiones

  • get_pg_stat_statements_top_queries (Requiere pg_stat_statements)
    • "Mostrar las 10 consultas más lentas."
    • "Analizar consultas lentas en la base de datos inventory."
    • 📈 Compatible con versiones: PG12 usa el mapeo total_time → total_exec_time; PG13+ usa columnas nativas
    • 💡 Multi-versión: Adapta automáticamente la estructura de consultas para compatibilidad con PostgreSQL 12-18
  • get_pg_stat_monitor_recent_queries (Opcional, usa pg_stat_monitor)
    • "Mostrar consultas recientes en tiempo real."
    • "Monitorear la actividad de consultas de los últimos 5 minutos."
    • 📈 Compatible con versiones: PG12 usa el mapeo total_time → total_exec_time; PG13+ usa columnas nativas
    • 💡 Multi-versión: Adapta automáticamente la estructura de consultas para compatibilidad con PostgreSQL 12-18

💡 Consejo profesional: Todas las herramientas admiten operaciones multi-base de datos usando el parámetro database_name. Esto permite a los superusuarios de PostgreSQL analizar y monitorear múltiples bases de datos desde una única instancia del servidor MCP.

Solución de Problemas

Problemas de Conexión

  1. Verifique el estado del servidor PostgreSQL
  2. Verifique los parámetros de conexión en el archivo .env
  3. Asegure la conectividad de red
  4. Verifique los permisos de usuario

Errores de Extensión

  1. Ejecuta get_server_info para verificar el estado de la extensión
  2. Instala las extensiones faltantes: 
    CREATE EXTENSION pg_stat_statements;
CREATE EXTENSION pg_stat_monitor;
  3. Reinicia PostgreSQL si es necesario

Problemas de Configuración

  1. "No se encontraron datos" para estadísticas de funciones: Verifica la configuración de track_functions

    SHOW track_functions;  -- Should be 'pl' or 'all'

    Solución rápida para servicios administrados (AWS RDS, etc.):

    ALTER SYSTEM SET track_functions = 'pl';
SELECT pg_reload_conf();

  2. Faltan datos de temporización de E/S: Habilita la recopilación de temporización

    SHOW track_io_timing;  -- Should be 'on'

    Solución rápida:

    ALTER SYSTEM SET track_io_timing = 'on';
SELECT pg_reload_conf();

  3. Aplica los cambios de configuración:

    • Autogestionado: Agrega la configuración a postgresql.conf y reinicia el servidor
    • Servicios administrados: Usa ALTER SYSTEM SET + SELECT pg_reload_conf()
    • Pruebas temporales: Usa SET parameter = value para la sesión actual
    • Genera algo de actividad en la base de datos para poblar las estadísticas

Problemas de Rendimiento

  1. Usa los parámetros de limit para reducir el tamaño de los resultados
  2. Ejecuta el monitoreo fuera de las horas pico
  3. Verifica la carga de la base de datos antes de ejecutar el análisis

Problemas de Compatibilidad de Versiones

Para más detalles, consulta la ## Matriz de Compatibilidad de Herramientas

  1. Ejecuta primero la verificación de compatibilidad:

    # "Use get_server_info to check version and available features"

  2. Comprendiendo la disponibilidad de funciones:

    • PostgreSQL 18: Todas las funciones, incluyendo E/S asíncrona, temporización de VACUUM, estadísticas por backend
    • PostgreSQL 17: Estadísticas separadas de checkpointer, eventos de espera, resumidor de WAL
    • PostgreSQL 16: Vista pg_stat_io
    • PostgreSQL 14+: Seguimiento de consultas paralelas
    • PostgreSQL 12-13: Solo funcionalidad principal

  3. Si una herramienta muestra "No disponible":

    • La función requiere una versión más reciente de PostgreSQL
    • La herramienta usará automáticamente la mejor alternativa disponible
    • Considera actualizar PostgreSQL para un monitoreo mejorado

Desarrollo

Pruebas y Desarrollo

# Clone and setup for development
git clone https://github.com/call518/MCP-PostgreSQL-Ops.git
cd MCP-PostgreSQL-Ops
uv sync

# Test with MCP Inspector (loads .env automatically)
./run-mcp-inspector-local.sh

# Direct execution methods:
# 1. Using uv run (recommended for development)
uv run mcp-postgresql-ops --log-level DEBUG

# 2. Module execution (requires PYTHONPATH)
PYTHONPATH=src python -m mcp_postgresql_ops --log-level DEBUG

# 3. After installation
mcp-postgresql-ops --log-level DEBUG

# Test version compatibility (requires different PostgreSQL versions)
# Modify POSTGRES_HOST in .env to point to different versions

Ejecución de Pruebas

Hay dos conjuntos de pruebas disponibles:

ConjuntoArchivoRequiere Docker
Pruebas unitarias (lógica de compatibilidad de versiones)tests/test_version_compat.pyNo
Pruebas de integración (todas las herramientas × PG 12–18)tests/test_tools_integration.pySí

uv run pytest inicia automáticamente los contenedores de prueba de Docker (PG 12–18), espera a que se inicialicen por completo, ejecuta todas las pruebas y luego elimina todo.

# Run all tests (unit + integration) — Docker is managed automatically
uv run pytest -v

# Unit tests only (no Docker needed)
uv run pytest tests/test_version_compat.py -v

# Integration tests only
uv run pytest tests/test_tools_integration.py -v

Nota: Docker debe estar en ejecución. El stack de pruebas usa los puertos 5412–5418 (PG 12–18).

Pruebas de Compatibilidad de Versiones

El servidor MCP se adapta automáticamente a las versiones de PostgreSQL 12-18. Para probar entre versiones:

  1. Configura bases de datos de prueba: Diferentes versiones de PostgreSQL (12, 14, 15, 16, 17, 18)
  2. Ejecuta pruebas de compatibilidad: Apunta a cada versión y verifica el comportamiento de las herramientas
  3. Verifica la detección de funciones: Asegura la detección correcta de versiones y la disponibilidad de funciones
  4. Verifica el comportamiento de respaldo: Confirma la degradación gradual en versiones anteriores

Notas de Seguridad

  • Todas las herramientas son de solo lectura - sin capacidades de modificación de datos
  • La información sensible (contraseñas) está enmascarada en las salidas
  • Sin ejecución directa de SQL - solo consultas predefinidas
  • Sigue el principio de privilegio mínimo

Contribuciones

🤝 ¿Tienes ideas? ¿Encontraste errores? ¿Quieres agregar funciones interesantes?

¡Siempre estamos emocionados de dar la bienvenida a nuevos contribuyentes! Ya sea corregir un error tipográfico, agregar una nueva herramienta de monitoreo o mejorar la documentación - cada contribución hace que este proyecto sea mejor.

Formas de contribuir:

  • 🐛 Reporta problemas o errores
  • 💡 Sugiere nuevas funciones de monitoreo de PostgreSQL
  • 📝 Mejora la documentación
  • 🚀 Envía solicitudes de extracción
  • ⭐ Marca el repositorio con una estrella si te resulta útil

Consejo profesional: El código base está diseñado para ser muy amigable para agregar nuevas herramientas. Revisa las funciones existentes de @mcp.tool() en mcp_main.py.

Documentación Swagger de MCPO

[URL de Swagger de MCPO] http://localhost:8003/postgresql-ops/docs

MCPO Swagger APIs

🔐 Seguridad y Autenticación

Autenticación con Token Bearer

Para el modo streamable-http, este servidor MCP admite autenticación con token Bearer para asegurar el acceso remoto. Esto es especialmente importante al ejecutar el servidor en entornos de producción.

Política predeterminada: REMOTE_AUTH_ENABLE tiene como valor predeterminado false si no está definido, es nulo o está vacío. Esto garantiza la compatibilidad hacia atrás y evita errores de inicio cuando la variable no está configurada.

Configuración

Habilitar autenticación:

# In .env file
REMOTE_AUTH_ENABLE=true
REMOTE_SECRET_KEY=my-test-secret-key-12345

O mediante CLI:

# Module method
python -m mcp_postgresql_ops --type streamable-http --auth-enable --secret-key my-test-secret-key-12345

# Script method
mcp-postgresql-ops --type streamable-http --auth-enable --secret-key my-test-secret-key-12345

Niveles de Seguridad

  1. Modo stdio (Predeterminado): Acceso solo local, no se necesita autenticación
  2. streamable-http + REMOTE_AUTH_ENABLE=false: Acceso remoto sin autenticación ⚠️ NO RECOMENDADO para producción
  3. streamable-http + REMOTE_AUTH_ENABLE=true: Acceso remoto con autenticación de token Bearer ✅ RECOMENDADO para producción

Configuración del Cliente

Cuando la autenticación está habilitada, los clientes MCP deben incluir el token Bearer en el encabezado de Authorization:

{
  "mcpServers": {
    "mcp-postgresql-ops": {
      "type": "streamable-http",
      "url": "http://your-server:8000/mcp",
      "headers": {
        "Authorization": "Bearer my-test-secret-key-12345"
      }
    }
  }
}

Mejores Prácticas de Seguridad

  • Habilita siempre la autenticación al usar el modo streamable-http en producción
  • Usa claves secretas fuertes y generadas aleatoriamente (se recomiendan 32+ caracteres)
  • Usa HTTPS cuando sea posible (configura un proxy inverso con SSL/TLS)
  • Restringe el acceso a la red usando firewalls o políticas de red
  • Rota las claves secretas regularmente para mayor seguridad
  • Monitorea los registros de acceso para detectar intentos de acceso no autorizado

Manejo de Errores

Cuando la autenticación falla, el servidor devuelve:

  • 401 No autorizado para tokens faltantes o inválidos
  • Mensajes de error detallados en formato JSON para depuración

🚀 Agregar Herramientas Personalizadas

Este servidor MCP está diseñado para una fácil extensibilidad. Sigue estos 4 simples pasos para agregar tus propias herramientas personalizadas:

Guía Paso a Paso

1. Agrega Funciones Auxiliares (Opcional)

Agrega funciones de datos reutilizables a src/mcp_postgresql_ops/functions.py:

async def get_your_custom_data(target_database: str = None, limit: int = 20) -> List[Dict[str, Any]]:
    """Your custom data retrieval function."""
    try:
        # Example implementation - adapt to your PostgreSQL needs
        query = """
        SELECT 
            schemaname,
            tablename,
            attname as column_name,
            n_distinct,
            most_common_vals,
            most_common_freqs
        FROM pg_stats 
        WHERE schemaname NOT IN ('information_schema', 'pg_catalog')
        ORDER BY schemaname, tablename, attname
        LIMIT $1
        """
        
        results = await execute_query(query, [limit], database=target_database)
        return results
        
    except Exception as e:
        logger.error(f"Failed to get custom data: {e}")
        raise

2. Crea Tu Herramienta MCP

Agrega tu función de herramienta a src/mcp_postgresql_ops/mcp_main.py:

@mcp.tool()
async def get_your_custom_analysis(limit: int = 50, database_name: Optional[str] = None) -> str:
    """
    [Tool Purpose]: Brief description of what your tool does
    
    [Exact Functionality]:
    - Feature 1: Data aggregation and analysis
    - Feature 2: Database monitoring and insights
    - Feature 3: Performance metrics and reporting
    
    [Required Use Cases]:
    - When user asks "your specific analysis request"
    - Your PostgreSQL-specific monitoring needs
    
    Args:
        limit: Maximum results (1-100)
        database_name: Target database name (optional, uses default if not specified)
    
    Returns:
        Formatted analysis results
    """
    try:
        # Always validate input limits
        limit = max(1, min(limit, 100))
        
        # Get your custom data
        results = await get_your_custom_data(target_database=database_name, limit=limit)
        
        if not results:
            return "No data found for custom analysis."
        
        # Format and return results
        return format_table_data(results, f"Custom Analysis Results (Top {len(results)})")
        
    except Exception as e:
        logger.error(f"Failed to get custom analysis: {e}")
        return f"Error: {str(e)}"

3. Actualiza las Importaciones

Agrega tu función auxiliar a la sección de importaciones en src/mcp_postgresql_ops/mcp_main.py (alrededor de la línea 30):

from .functions import (
    execute_query,
    execute_single_query,
    format_table_data,
    format_bytes,
    format_duration,
    get_server_version,
    check_extension_exists,
    get_pg_stat_statements_data,
    get_pg_stat_monitor_data,
    sanitize_connection_info,
    read_prompt_template,
    parse_prompt_sections,
    get_current_database_name,
    POSTGRES_CONFIG,
    get_your_custom_data,  # Add your new function here
)

4. Actualiza la Plantilla de Prompt (Recomendado)

Agrega la descripción de tu herramienta a src/mcp_postgresql_ops/prompt_template.md para un mejor reconocimiento del lenguaje natural:

### **Your Custom Analysis Tool**

### X. **get_your_custom_analysis**
**Purpose**: Brief description of what your tool does
**Usage**: "Show me your custom analysis" or "Get custom analysis for database_name"
**Features**: Data aggregation, database monitoring, performance metrics
**Optional**: `database_name` parameter for specific database analysis
**Limit**: Results limited to 1-100 records for performance

5. Prueba Tu Herramienta

# Local testing with MCP Inspector
./run-mcp-inspector-local.sh

# Or test with Docker stack
docker-compose up -d
docker-compose logs -f mcp-server

# Test with natural language queries:
# "Show me your custom analysis"
# "Get custom analysis for ecommerce database"
# "Analyze custom data with limit 25"

Notas Importantes

  • Soporte Multi-Base de Datos: Todas las herramientas admiten el parámetro opcional database_name para apuntar a bases de datos específicas
  • Validación de Entrada: Siempre valida los parámetros de limit con max(1, min(limit, 100))
  • Manejo de Errores: Devuelve mensajes de error amigables en lugar de lanzar excepciones
  • Registro: Usa logger.error() para depuración mientras devuelves mensajes de error limpios a los usuarios
  • Compatibilidad con PostgreSQL: Tus consultas personalizadas deben funcionar en PostgreSQL 12-18
  • Dependencias de Extensiones: Si tu herramienta requiere extensiones específicas, verifica la disponibilidad con check_extension_exists()

Patrones Avanzados

Para consultas conscientes de la versión o funciones dependientes de extensiones, consulta herramientas existentes como get_pg_stat_statements_top_queries para ver patrones de referencia.

¡Eso es todo! Tu herramienta personalizada está lista para usarse con consultas en lenguaje natural a través de cualquier cliente MCP.

Licencia

Usa, modifica y distribuye libremente bajo la Licencia MIT.

⭐ Otros Proyectos

Otros servidores MCP del mismo autor: