Skip to main content
Glama
redshift-utils-mcp

redshift-utils-mcp

Servidor MCP de Redshift Utils

Descripción general

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.

Conecta los Modelos de Lenguaje Grandes (LLM) o los asistentes de IA (como los de Claude, Cursor o aplicaciones personalizadas) con el almacén de datos de Redshift, lo que permite un acceso y una interacción seguros y estandarizados con los datos. Esto permite a los usuarios consultar datos, comprender la estructura de la base de datos y realizar operaciones de monitorización y diagnóstico mediante lenguaje natural o indicaciones basadas en IA.

Este servidor es para desarrolladores, analistas de datos o equipos que buscan integrar las capacidades de LLM directamente con su entorno de datos de Amazon Redshift de manera estructurada y segura.

Related MCP server: Redshift MCP Server

Tabla de contenido

Características

  • ✨ Conexión segura a Redshift (a través de API de datos): se conecta a su clúster de Amazon Redshift mediante la API de datos de AWS Redshift a través de Boto3, aprovechando AWS Secrets Manager para credenciales administradas de forma segura a través de variables de entorno.

  • 🔍 Descubrimiento de esquemas: expone recursos MCP para enumerar esquemas y tablas dentro de un esquema específico.

  • 📊 Metadatos y estadísticas: proporciona una herramienta ( handle_inspect_table ) para recopilar metadatos de tablas detallados, estadísticas (como tamaño, recuento de filas, sesgo, obsolescencia de las 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 en la base de datos Redshift, lo que permite la recuperación de datos en función de solicitudes LLM.

  • 📈 Análisis del rendimiento de consultas: incluye una herramienta ( handle_diagnose_query_performance ) para recuperar y analizar el plan de ejecución, las métricas y los datos históricos de un ID de consulta específico.

  • 🔍 Inspección de tabla: proporciona una herramienta ( handle_inspect_table ) para realizar una inspección integral de una tabla, incluido el diseño, el almacenamiento, el estado y el uso.

  • 🩺 Comprobación del estado del clúster: ofrece una herramienta ( handle_check_cluster_health ) para realizar una evaluación básica o completa del estado del clúster mediante varias consultas de diagnóstico.

  • 🔒 Diagnóstico de bloqueo: proporciona una herramienta ( handle_diagnose_locks ) para identificar e informar sobre la contención de bloqueos actuales y las sesiones de bloqueo.

  • Monitoreo de carga de trabajo: incluye una herramienta ( handle_monitor_workload ) para analizar patrones de carga de trabajo del clúster durante una ventana 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 específica.

  • 🛡️ Saneamiento de entrada: utiliza consultas parametrizadas a través del cliente de API de datos Boto3 Redshift cuando corresponde para mitigar los riesgos de inyección de 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).

Prerrequisitos

Software:

  • Python 3.8+

  • uv (gestor de paquetes recomendado)

  • Git (para clonar el repositorio)

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 acceder al secreto de Secrets Manager especificado ( secretsmanager:GetSecretValue ).

  • Una cuenta de usuario de Redshift cuyas credenciales se almacenan en AWS Secrets Manager. Este usuario necesita los permisos necesarios en Redshift para realizar las acciones habilitadas por este servidor (p. ej., CONNECT con la base de datos, SELECT en las tablas de destino, SELECT en las vistas del sistema relevantes como pg_class , pg_namespace , svv_all_schemas , svv_tables y `svv_table_info`). Se recomienda encarecidamente usar un rol con el principio de mínimo privilegio. Consulte Consideraciones de seguridad .

Cartas credenciales:

Los datos de su conexión a Redshift se gestionan mediante AWS Secrets Manager, y el servidor se conecta mediante la API de datos de Redshift. Necesita:

  • El identificador del grupo 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 credenciales/región predeterminadas.

Estos detalles se configurarán a través de variables de entorno como se detalla en la sección Configuración .

Configuración

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

Ejemplo usando la exportación de 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 la variable

Requerido

Descripción

Valor de ejemplo

REDSHIFT_CLUSTER_ID

Sí

Su identificador de clúster Redshift.

my-redshift-cluster

REDSHIFT_DATABASE

Sí

El nombre de la base de datos a la que conectarse.

mydatabase

REDSHIFT_SECRET_ARN

Sí

ARN de AWS Secrets Manager para credenciales de Redshift.

arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret-abcdef

AWS_REGION

Sí

Región de AWS para API de datos y Secrets Manager.

us-east-1

AWS_DEFAULT_REGION

No

Alternativa a AWS_REGION para especificar la región de AWS.

us-west-2

AWS_PROFILE

No

Nombre de perfil de AWS que se utilizará desde su archivo de credenciales (~/.aws/...).

my-redshift-profile

Nota: asegúrese de que las credenciales de AWS utilizadas por Boto3 (a través del 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

Conexión con Claude Desktop / Consola Antrópica:

Agregue el siguiente bloque de configuración a su archivo mcp.json . Ajuste command , args , env y workingDirectory según su método de instalación y configuración.

{
  "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 Cursor IDE:

  1. Inicie el servidor MCP localmente siguiendo las instrucciones de la sección Uso / Inicio rápido .

  2. En Cursor, abra la Paleta de comandos (Cmd/Ctrl + Shift + P).

  3. Escriba "Conectarse al servidor MCP" o navegue a la configuración de MCP.

  4. Agregar una nueva conexión al servidor.

  5. Seleccione el tipo de transporte stdio .

  6. Introduzca el comando y los argumentos necesarios para iniciar el servidor ( uvx run redshift_utils_mcp ). Asegúrese de que todas las variables de entorno necesarias estén disponibles para el comando que se está ejecutando.

  7. El cursor debe detectar el servidor y sus herramientas/recursos disponibles.

Recursos MCP disponibles

Patrón de URI de recurso

Descripción

Ejemplo de URI

/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://schemas

Enumera todos los esquemas definidos por el usuario accesibles en la base de datos conectada.

redshift://schemas

redshift://wlm/configuration

Recupera los detalles de configuración actuales de Gestión de carga de trabajo (WLM).

redshift://wlm/configuration

redshift://schema/{schema_name}/tables

Enumera 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 a los esquemas/tablas depende de los permisos otorgados al usuario de Redshift, configurados mediante REDSHIFT_SECRET_ARN .

Herramientas MCP disponibles

Nombre de la herramienta

Descripción

Parámetros clave (obligatorios*)

Ejemplo de invocación

handle_check_cluster_health

Realiza una evaluación del estado del clúster 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_locks

Identifica contención de bloqueo activa y sesiones de bloqueo en el clúster.

min_wait_seconds (opcional)

use_mcp_tool("redshift-admin", "handle_diagnose_locks", {"min_wait_seconds": 10})

handle_diagnose_query_performance

Analiza el rendimiento de ejecución de una consulta específica, incluido el plan, las métricas y los datos históricos.

query_id *

use_mcp_tool("redshift-admin", "handle_diagnose_query_performance", {"query_id": 12345})

handle_execute_ad_hoc_query

Ejecuta 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_definition

Recupera la declaración DDL (lenguaje de definición de datos) ( SHOW TABLE ) para una tabla específica.

schema_name , table_name

use_mcp_tool("redshift-admin", "handle_get_table_definition", {"schema_name": "public", ...})

handle_inspect_table

Recupera información detallada sobre una tabla Redshift específica, que abarca el diseño, el almacenamiento, el estado y el uso.

schema_name , table_name

use_mcp_tool("redshift-admin", "handle_inspect_table", {"schema_name": "analytics", ...})

handle_monitor_workload

Analiza los patrones de carga de trabajo del clúster durante un período de tiempo específico 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})

HACER

  • [ ] Mejorar las opciones de aviso

  • [ ] Agregar soporte para más métodos de credenciales

  • [ ] Agregar soporte para Redshift Serverless

Contribuyendo

¡Agradecemos sus contribuciones! Por favor, sigan estas pautas.

Encontrar/Reportar problemas: Consulta la página de problemas de GitHub para ver errores o solicitudes de funciones. Si lo necesitas, puedes abrir un nuevo problema.

La seguridad es fundamental al proporcionar acceso a bases de datos a través de un servidor MCP. Tenga en cuenta lo siguiente:

🔒 Administración de credenciales: Este servidor utiliza AWS Secrets Manager a través de la API de datos de Redshift, lo cual es más seguro que almacenar las credenciales directamente en variables de entorno o archivos de configuración. Asegúrese de que las credenciales de AWS que utiliza Boto3 (a través del entorno, perfil o rol de IAM) se administren de forma segura y tengan los permisos mínimos necesarios. Nunca envíe sus credenciales de AWS ni archivos .env que contengan secretos al control de versiones.

🛡️ Principio de privilegios mínimos: Configure el usuario de Redshift cuyas credenciales se encuentran en AWS Secrets Manager con los permisos mínimos necesarios para la funcionalidad prevista del servidor. Por ejemplo, si solo se necesita acceso de lectura, otorgue únicamente los privilegios CONNECT y SELECT en los esquemas/tablas necesarios, y SELECT en las vistas del sistema requeridas. Evite usar usuarios con privilegios elevados, como admin o el superusuario del clúster.

Para obtener orientación sobre la creación de usuarios restringidos de Redshift y la administración de permisos, consulte el sitio oficial ( https://docs.aws.amazon.com/redshift/latest/mgmt/security.html ).

Licencia

Este proyecto está licenciado bajo la Licencia MIT. Consulte el archivo (LICENCIA) para más detalles.

Referencias

Available Tools

7 tools
handle_check_cluster_healthA

Performs a health assessment of the Redshift cluster.

Executes a series of diagnostic SQL scripts concurrently based on the
specified level ('basic' or 'full'). Aggregates raw results or errors
from each script into a dictionary.

Args:
    ctx: The MCP context object.
    level: Level of detail: 'basic' for operational status, 'full' for
           comprehensive table design/maintenance checks. Defaults to 'basic'.
    time_window_days: Lookback period in days for time-sensitive checks
                      (e.g., queue waits, commit waits). Defaults to 1.

Returns:
    A dictionary where keys are script names and values are either the raw
    list of dictionary results from the SQL query or an Exception object
    if that specific script failed.

Raises:
    DataApiError: If a critical error occurs during script execution that
                  prevents gathering results (e.g., config error). Individual
                  script errors are captured within the returned dictionary.

Inputs: level, time_window_days.

handle_diagnose_locksA

Identifies active lock contention in the cluster.

Fetches all current lock information and then filters it based on the
optional target PID, target table name, and minimum wait time.
Formats the results into a list of contention details and a summary.

Args:
    ctx: The MCP context object.
    target_pid: Optional: Filter results to show locks held by or waited
                for by this specific process ID (PID).
    target_table_name: Optional: Filter results for locks specifically on
                       this table name (schema qualification recommended
                       if ambiguous).
    min_wait_seconds: Minimum seconds a lock must be in a waiting state
                      to be included. Defaults to 5.

Returns:
    A list of dictionaries, where each dictionary represents a row
    from the lock contention query result.

Raises:
    DataApiError: If fetching the initial lock information fails.

Inputs: min_wait_seconds, target_pid, target_table_name.

handle_diagnose_query_performanceA

Analyzes a specific query's execution performance.

Fetches query text, execution plan, metrics, alerts, compilation info,
skew details, and optionally historical run data. Uses a formatting
utility to synthesize this into a structured report with potential issues
and recommendations.

Args:
    ctx: The MCP context object.
    query_id: The numeric ID of the Redshift query to analyze.
    compare_historical: Fetch performance data for previous runs of the
                       same query text. Defaults to True.

Returns:
    A dictionary conforming to DiagnoseQueryPerformanceResult structure:
    - On success: Contains detailed performance breakdown, issues, recommendations.
    - On query not found: Raises QueryNotFound exception.
    - On other errors: Raises DataApiError or similar for FastMCP to handle.

Raises:
    DataApiError: If a critical error occurs during script execution or parsing.
    QueryNotFound: If the specified query_id cannot be found in key tables.

Inputs: query_id (required), compare_historical.

handle_execute_ad_hoc_queryA

Executes an arbitrary SQL query provided by the user via Redshift Data API.

Designed as an escape hatch for advanced users or queries not covered by
specialized tools. Returns a structured dictionary indicating success
(with results) or failure (with error details).

Args:
    ctx: The MCP context object.
    sql_query: The exact SQL query string to execute.

Returns:
    A dictionary conforming to ExecuteAdHocQueryResult structure:
    - On success: {"status": "success", "columns": [...], "rows": [...], "row_count": ...}
    - On error: {"status": "error", "error_message": "...", "error_type": "..."}
    (Note: Actual return might be handled by FastMCP error handling for raised exceptions)

Raises:
    DataApiConfigError: If configuration is invalid.
    SqlExecutionError: If the SQL execution itself fails.
    DataApiTimeoutError: If the Data API call times out.
    DataApiError: For other Data API related errors or unexpected issues.
    ClientError: For AWS client-side errors.

Inputs: sql_query (required).

handle_get_table_definitionA

Retrieves the DDL (Data Definition Language) statement for a specific table.

Executes a SQL script designed to generate or retrieve the CREATE TABLE
statement for the given table.

Args:
    ctx: The MCP context object.
    schema_name: The schema name of the table.
    table_name: The name of the table.

Returns:
    A dictionary conforming to GetTableDefinitionResult structure:
    - On success: {"status": "success", "ddl": "<CREATE TABLE statement>"}
    - On table not found or DDL retrieval error:
      {"status": "error", "error_message": "...", "error_type": "..."}

Raises:
    TableNotFound: If the specified table is not found.
    DataApiError: If a critical, unexpected error occurs during execution.

Inputs: schema_name (required), table_name (required).

handle_inspect_tableA

Retrieves detailed information about a specific Redshift table.

Fetches table OID, then concurrently executes various inspection scripts
covering design, storage, health, usage, and encoding.

Args:
    ctx: The MCP context object.
    schema_name: The schema name of the table.
    table_name: The name of the table.

Returns:
    A dictionary where keys are script names and values are either the raw
    list of dictionary results from the SQL query, the extracted DDL string,
    or an Exception object if that specific script failed.
    - On success: Dictionary containing raw results or Exception objects for each script.
    - On table not found: Raises TableNotFound exception.
    - On critical errors (e.g., OID lookup failure): Raises DataApiError or similar.

Raises:
    DataApiError: If a critical error occurs during script execution.
    TableNotFound: If the specified table cannot be found via its OID.

Inputs: schema_name (required), table_name (required).

handle_monitor_workloadA

Analyzes cluster workload patterns over a specified time window.

Executes various SQL scripts concurrently to gather data on resource usage,
WLM performance, top queries, queuing, COPY performance, and disk-based
queries. Returns a dictionary containing the raw results (or Exceptions)
keyed by the script name.

Args:
    ctx: The MCP context object.
    time_window_days: Lookback period in days for the workload analysis.
                      Defaults to 2.
    top_n_queries: Number of top queries (by total execution time) to
                   consider for the 'top_queries.sql' script. Defaults to 10.

Returns:
    A dictionary where keys are script names (e.g., 'workload/top_queries.sql')
    and values are either a list of result rows (as dictionaries) or the
    Exception object if that script failed.

Raises:
    DataApiError: If a critical error occurs during configuration loading.
                  (Note: Individual script errors are returned in the result dict).

Inputs: time_window_days, top_n_queries.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool has a distinct purpose with clear boundaries: cluster health assessment, lock diagnosis, query performance analysis, ad-hoc query execution, table definition retrieval, table inspection, and workload monitoring. There is no functional overlap between tools, and the descriptions clearly differentiate their specific use cases.

    Naming Consistency3/5

    All tools follow a 'handle_verb_noun' prefix pattern, which provides some consistency. However, the verb choices are mixed ('check', 'diagnose', 'execute', 'get', 'inspect', 'monitor'), making the naming somewhat inconsistent in terms of action semantics. The structure is predictable but the verb selection lacks uniformity.

    Tool Count5/5

    With 7 tools, this server is well-scoped for Redshift cluster diagnostics and management. Each tool serves a specific, valuable function in the domain, and there are no redundant or trivial tools. The count is appropriate for covering key operational and troubleshooting tasks without being overwhelming.

    Completeness4/5

    The toolset covers essential diagnostic and operational areas for Redshift: health checks, lock analysis, query performance, ad-hoc queries, table definitions, table inspection, and workload monitoring. Minor gaps exist, such as lack of tools for cluster configuration changes, user/role management, or backup operations, but core diagnostic workflows are well-covered.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      Model Context Protocol (MCP) server that integrates Redash with AI assistants like Claude, allowing them to query data, manage visualizations, and interact with dashboards through natural language.
      67
      4,563 npm
      108
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      A Model Context Protocol server that enables AI assistants to interact with Amazon Redshift databases, allowing for schema exploration, query execution, and statistics collection.
      3
      2
      Apache 2.0