Redshift Utils MCP Server

Realizar acciones de base de datos en Amazon Redshift a través de su API de datos.

GitHub
6
Prueba este MCPPatrocinado

Documentación

Redshift Utils MCP Server

Resumen

Este proyecto implementa un servidor de Protocolo de Contexto de Modelo (MCP) diseñado específicamente para interactuar con bases de datos de Amazon Redshift.

Cierra la brecha entre los Modelos de Lenguaje de Gran Tamaño (LLMs) o asistentes de IA (como los de Claude, Cursor o aplicaciones personalizadas) y su almacén de datos de Redshift, permitiendo un acceso e interacción de datos seguro y estandarizado. Esto permite a los usuarios consultar datos, comprender la estructura de la base de datos y realizar operaciones de monitoreo/diagnóstico utilizando lenguaje natural o indicaciones impulsadas por IA.

Este servidor está dirigido a desarrolladores, analistas de datos o equipos que buscan integrar capacidades de LLM directamente con su entorno de datos de Amazon Redshift de manera estructurada y segura.

Tabla de Contenidos

Características

  • ✨ Conexión Segura a Redshift (a través de Data API): Se conecta a su clúster de Amazon Redshift utilizando la API de Datos de Redshift de AWS a través de Boto3, aprovechando AWS Secrets Manager para credenciales gestionadas de forma segura mediante variables de entorno.
  • 🔍 Descubrimiento de Esquemas: Expone recursos MCP para listar esquemas y tablas dentro de un esquema especificado.
  • 📊 Metadatos y Estadísticas: Proporciona una herramienta (handle_inspect_table) para recopilar metadatos detallados de tablas, estadísticas (como tamaño, recuentos de filas, sesgo, antigüedad de estadísticas) y estado de mantenimiento.
  • 📝 Ejecución de Consultas de Solo Lectura: Ofrece una herramienta MCP segura (handle_execute_ad_hoc_query) para ejecutar consultas SELECT arbitrarias contra la base de datos de Redshift, permitiendo la recuperación de datos basada en solicitudes de LLM.
  • 📈 Análisis de Rendimiento de Consultas: Incluye una herramienta (handle_diagnose_query_performance) para recuperar y analizar el plan de ejecución, métricas y datos históricos de un ID de consulta específico.
  • 🔍 Inspección de Tablas: Proporciona una herramienta (handle_inspect_table) para realizar una inspección exhaustiva de una tabla, incluyendo diseño, almacenamiento, salud y uso.
  • 🩺 Verificación de Salud del Clúster: Ofrece una herramienta (handle_check_cluster_health) para realizar una evaluación de salud básica o completa del clúster utilizando diversas consultas de diagnóstico.
  • 🔒 Diagnóstico de Bloqueos: Proporciona una herramienta (handle_diagnose_locks) para identificar e informar sobre la contención de bloqueos actual y las sesiones bloqueantes.
  • 📊 Monitoreo de Carga de Trabajo: Incluye una herramienta (handle_monitor_workload) para analizar patrones de carga de trabajo del clúster en un intervalo de tiempo, cubriendo WLM, consultas principales y uso de recursos.
  • 📝 Recuperación de DDL: Ofrece una herramienta (handle_get_table_definition) para recuperar la salida de SHOW TABLE (DDL) para una tabla especificada.
  • 🛡️ Saneamiento de Entradas: Utiliza consultas parametrizadas a través del cliente de la API de Datos de Redshift de Boto3 cuando corresponde para mitigar riesgos de inyección SQL.
  • 🧩 Interfaz MCP Estandarizada: Se adhiere a la especificación del Protocolo de Contexto de Modelo para una integración perfecta con clientes compatibles (por ejemplo, Claude Desktop, Cursor IDE, aplicaciones personalizadas).

Requisitos Previos

Software:

  • Python 3.10+
  • uv (gestor de paquetes recomendado) o pip

Infraestructura y Acceso:

  • Acceso a un clúster de Amazon Redshift.
  • Una cuenta de AWS con permisos para usar la API de Datos de Redshift (redshift-data:*) y acceso al secreto especificado de Secrets Manager (secretsmanager:GetSecretValue).
  • Una cuenta de usuario de Redshift cuyas credenciales estén almacenadas en AWS Secrets Manager. Este usuario necesita los permisos necesarios dentro de Redshift para realizar las acciones habilitadas por este servidor (por ejemplo, CONNECT a la base de datos, SELECT en tablas objetivo, SELECT en vistas del sistema relevantes como pg_class, pg_namespace, svv_all_schemas, svv_tables, `svv_table_info``). Se recomienda encarecidamente utilizar un rol con el principio de privilegio mínimo. Consulte Consideraciones de Seguridad.

Credenciales:

Los detalles de conexión de su Redshift se gestionan a través de AWS Secrets Manager, y el servidor se conecta utilizando la API de Datos de Redshift. Necesita:

  • El identificador del clúster de Redshift.
  • El nombre de la base de datos dentro del clúster.
  • El ARN del secreto de AWS Secrets Manager que contiene las credenciales de la base de datos (nombre de usuario y contraseña).
  • La región de AWS donde residen el clúster y el secreto.
  • Opcionalmente, un nombre de perfil de AWS si no se utilizan las credenciales/región predeterminadas.

Estos detalles se configurarán mediante variables de entorno como se detalla en la sección Configuración.

Instalación

Instalar desde PyPI (Recomendado)

La forma más fácil de instalar el Redshift Utils MCP Server es directamente desde PyPI:

# Using pip
pip install redshift-utils-mcp

# Using uv (recommended)
uv pip install redshift-utils-mcp

Instalar desde el Código Fuente

Alternativamente, puede instalar desde el repositorio fuente:

# Clone the repository
git clone https://github.com/vinodismyname/redshift-utils-mcp.git
cd redshift-utils-mcp

# Install using uv (recommended)
uv sync

# Or install using pip
pip install -e .

Configuración

Establecer Variables de Entorno: Este servidor requiere las siguientes variables de entorno para conectarse a su clúster de Redshift a través de la API de Datos de AWS. Puede configurarlas directamente en su shell, usando un archivo de servicio systemd, un archivo de entorno de Docker, o creando un archivo .env en el directorio raíz del proyecto (si usa una herramienta como uv o python-dotenv que admita la carga desde .env).

Ejemplo usando export en shell:

export REDSHIFT_CLUSTER_ID="your-cluster-id"
export REDSHIFT_DATABASE="your_database_name"
export REDSHIFT_SECRET_ARN="arn:aws:secretsmanager:us-east-1:123456789012:secret:your-redshift-secret-XXXXXX"
export AWS_REGION="us-east-1" # Or AWS_DEFAULT_REGION
# export AWS_PROFILE="your-aws-profile-name" # Optional

Ejemplo de archivo .env (ver .env.example):

# .env file for Redshift MCP Server configuration
# Ensure this file is NOT committed to version control if it contains secrets. Add it to .gitignore.

REDSHIFT_CLUSTER_ID="your-cluster-id"
REDSHIFT_DATABASE="your_database_name"
REDSHIFT_SECRET_ARN="arn:aws:secretsmanager:us-east-1:123456789012:secret:your-redshift-secret-XXXXXX"
AWS_REGION="us-east-1" # Or AWS_DEFAULT_REGION
# AWS_PROFILE="your-aws-profile-name" # Optional

Tabla de Variables Requeridas:

Nombre de VariableRequeridaDescripciónValor de Ejemplo
REDSHIFT_CLUSTER_IDSíIdentificador de su clúster de Redshift.my-redshift-cluster
REDSHIFT_DATABASESíEl nombre de la base de datos a la que conectarse.mydatabase
REDSHIFT_SECRET_ARNSíARN de AWS Secrets Manager para credenciales de Redshift.arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret-abcdef
AWS_REGIONSíRegión de AWS para Data API y Secrets Manager.us-east-1
AWS_DEFAULT_REGIONNoAlternativa a AWS_REGION para especificar la región de AWS.us-west-2
AWS_PROFILENoNombre del perfil de AWS a usar desde su archivo de credenciales (~/.aws/...).my-redshift-profile

Nota: Asegúrese de que las credenciales de AWS utilizadas por Boto3 (a través de entorno, perfil o rol de IAM) tengan permisos para acceder al REDSHIFT_SECRET_ARN especificado y usar la API de Datos de Redshift (redshift-data:*).

Uso

Después de la instalación, puede ejecutar el servidor directamente desde la línea de comandos:

# If installed from PyPI
redshift-utils-mcp

# Or using uvx (no installation required)
uvx redshift-utils-mcp

Conexión con Claude Desktop / Consola de Anthropic:

Agregue el siguiente bloque de configuración a su archivo mcp.json:

{
  "mcpServers": {
    "redshift-utils-mcp": {
      "command": "uvx",
      "args": ["redshift-utils-mcp"],
      "env": {
        "REDSHIFT_CLUSTER_ID":"your-cluster-id",
        "REDSHIFT_DATABASE":"your_database_name",
        "REDSHIFT_SECRET_ARN":"arn:aws:secretsmanager:...",
        "AWS_REGION": "us-east-1"
      }
  }
}

Conexión con Claude Code CLI:

Use la CLI de Claude para agregar la configuración del servidor:

claude mcp add redshift-utils-mcp \
  -e REDSHIFT_CLUSTER_ID="your-cluster-id" \
  -e REDSHIFT_DATABASE="your_database_name" \
  -e REDSHIFT_SECRET_ARN="arn:aws:secretsmanager:..." \
  -e AWS_REGION="us-east-1" \
  -- uvx redshift-utils-mcp

Conexión con Cursor IDE:

  1. Inicie el servidor MCP localmente usando las instrucciones en la sección Uso / Inicio Rápido.
  2. En Cursor, abra la Paleta de Comandos (Cmd/Ctrl + Shift + P).
  3. Escriba "Connect to MCP Server" o navegue a la configuración de MCP.
  4. Agregue una nueva conexión de servidor.
  5. Elija el tipo de transporte stdio.
  6. Ingrese el comando y los argumentos necesarios para iniciar su servidor (uvx run redshift_utils_mcp). Asegúrese de que las variables de entorno necesarias estén disponibles para el comando que se ejecuta.
  7. Cursor debería detectar el servidor y sus herramientas/recursos disponibles.

Recursos MCP Disponibles

Patrón de URI de RecursoDescripciónURI de Ejemplo
/scripts/{script_path}Recupera el contenido sin procesar de un archivo de script SQL del directorio sql_scripts del servidor./scripts/health/disk_usage.sql
redshift://schemasLista todos los esquemas definidos por el usuario accesibles en la base de datos conectada.redshift://schemas
redshift://wlm/configurationRecupera los detalles de configuración actuales de Gestión de Carga de Trabajo (WLM).redshift://wlm/configuration
redshift://schema/{schema_name}/tablesLista todas las tablas y vistas accesibles dentro del {schema_name} especificado.redshift://schema/public/tables

Reemplace {script_path} y {schema_name} con los valores reales al realizar solicitudes. La accesibilidad de esquemas/tablas depende de los permisos otorgados al usuario de Redshift configurado a través de REDSHIFT_SECRET_ARN.

Herramientas MCP Disponibles

Nombre de la herramientaDescripciónParámetros clave (obligatorios*)Ejemplo de invocación
handle_check_cluster_healthRealiza una evaluación de salud del clúster de Redshift utilizando un conjunto de scripts SQL de diagnóstico.level (opcional), time_window_days (opcional)use_mcp_tool("redshift-admin", "handle_check_cluster_health", {"level": "full"})
handle_diagnose_locksIdentifica contención de bloqueos activos y sesiones bloqueantes en el clúster.min_wait_seconds (opcional)use_mcp_tool("redshift-admin", "handle_diagnose_locks", {"min_wait_seconds": 10})
handle_diagnose_query_performanceAnaliza el rendimiento de ejecución de una consulta específica, incluyendo plan, métricas y datos históricos.query_id*use_mcp_tool("redshift-admin", "handle_diagnose_query_performance", {"query_id": 12345})
handle_execute_ad_hoc_queryEjecuta una consulta SQL arbitraria proporcionada por el usuario a través de la API de datos de Redshift. Diseñado como una vía de escape.sql_query*use_mcp_tool("redshift-admin", "handle_execute_ad_hoc_query", {"sql_query": "SELECT ..."})
handle_get_table_definitionRecupera la declaración DDL (lenguaje de definición de datos) (SHOW TABLE) para una tabla específica.schema_name, table_nameuse_mcp_tool("redshift-admin", "handle_get_table_definition", {"schema_name": "public", ...})
handle_inspect_tableRecupera información detallada sobre una tabla específica de Redshift, cubriendo diseño, almacenamiento, salud y uso.schema_name, table_nameuse_mcp_tool("redshift-admin", "handle_inspect_table", {"schema_name": "analytics", ...})
handle_monitor_workloadAnaliza patrones de carga de trabajo del clúster durante un intervalo de tiempo especificado utilizando varios scripts de diagnóstico.time_window_days (opcional), top_n_queries (opcional)use_mcp_tool("redshift-admin", "handle_monitor_workload", {"time_window_days": 7})

PENDIENTES

  • Mejorar las opciones de prompt
  • Agregar soporte para más métodos de credenciales
  • Agregar soporte para Redshift Serverless

Referencias