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 deSHOW 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.,
CONNECTcon la base de datos,SELECTen las tablas de destino,SELECTen las vistas del sistema relevantes comopg_class,pg_namespace,svv_all_schemas,svv_tablesy `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" # OptionalEjemplo 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" # OptionalTabla de variables requeridas:
Nombre de la variable | Requerido | Descripción | Valor de ejemplo |
| Sí | Su identificador de clúster Redshift. |
|
| Sí | El nombre de la base de datos a la que conectarse. |
|
| Sí | ARN de AWS Secrets Manager para credenciales de Redshift. |
|
| Sí | Región de AWS para API de datos y Secrets Manager. |
|
| No | Alternativa a |
|
| No | Nombre de perfil de AWS que se utilizará desde su archivo de credenciales (~/.aws/...). |
|
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:
Inicie el servidor MCP localmente siguiendo las instrucciones de la sección Uso / Inicio rápido .
En Cursor, abra la Paleta de comandos (Cmd/Ctrl + Shift + P).
Escriba "Conectarse al servidor MCP" o navegue a la configuración de MCP.
Agregar una nueva conexión al servidor.
Seleccione el tipo de transporte
stdio.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.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 |
| Recupera el contenido sin procesar de un archivo de script SQL del directorio |
|
| Enumera todos los esquemas definidos por el usuario accesibles en la base de datos conectada. |
|
| Recupera los detalles de configuración actuales de Gestión de carga de trabajo (WLM). |
|
| Enumera todas las tablas y vistas accesibles dentro del |
|
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 |
| Realiza una evaluación del estado del clúster Redshift utilizando un conjunto de scripts SQL de diagnóstico. |
|
|
| Identifica contención de bloqueo activa y sesiones de bloqueo en el clúster. |
|
|
| Analiza el rendimiento de ejecución de una consulta específica, incluido el plan, las métricas y los datos históricos. |
|
|
| 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. |
|
|
| Recupera la declaración DDL (lenguaje de definición de datos) ( |
|
|
| Recupera información detallada sobre una tabla Redshift específica, que abarca el diseño, el almacenamiento, el estado y el uso. |
|
|
| Analiza los patrones de carga de trabajo del clúster durante un período de tiempo específico utilizando varios scripts de diagnóstico. |
|
|
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
Este proyecto se basa en gran medida en la especificación del Protocolo de Contexto de Modelo .
Desarrollado utilizando el SDK oficial de MCP proporcionado por Model Context Protocol .
Utiliza el AWS SDK para Python ( Boto3 ) para interactuar con la API de datos de Amazon Redshift .
Muchos de los scripts SQL de diagnóstico están adaptados del excelente repositorio awslabs/amazon-redshift-utils .
Available Tools
7 toolshandle_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
Scored across 7 tools
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.
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.
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.
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
Related MCP Connectors
Hosted SQL Server MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Hosted BigQuery MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Hosted Amazon Seller and Vendor MCP server for Claude, ChatGPT, Cursor, Codex, Gemini, Copilot.
Hosted Amazon Seller Central and Amazon Ads MCP server for Claude, ChatGPT, Cursor, and agents.
Related MCP Servers
- AlicenseBqualityBmaintenanceModel 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.674,563 npm108MIT
- AlicenseBqualityDmaintenanceA Model Context Protocol server that enables AI assistants to interact with Amazon Redshift databases, allowing for schema exploration, query execution, and statistics collection.32Apache 2.0
- AlicenseAqualityBmaintenanceA Snowflake MCP server — SQL queries, schema exploration, and data insights for AI assistants6307 PyPI2MIT
- AlicenseAqualityDmaintenanceModel Context Protocol (MCP) server for Redash - manage queries, dashboards, and visualizations through AI assistants like Claude.6202 PyPIMIT