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.

Tabla de contenido

• Servidor MCP de Redshift Utils
  • Descripción general
  • Tabla de contenido
  • Características
  • Prerrequisitos
  • Configuración
  • Uso
    • Conexión con Claude Desktop / Consola Antrópica:
    • Conexión con Cursor IDE:
    • Recursos MCP disponibles
    • Herramientas MCP disponibles
  • HACER
  • Contribuyendo
  • Licencia
  • Referencias

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 las credenciales o la 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:

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

Tabla de variables requeridas:

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.

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

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

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 .