Redshift Utils MCP Server

Realizar ações de banco de dados no Amazon Redshift por meio de sua API de Dados.

GitHub
6
Experimente este MCPPatrocinado

Documentação

Redshift Utils MCP Server

Visão Geral

Este projeto implementa um servidor Model Context Protocol (MCP) projetado especificamente para interagir com bancos de dados Amazon Redshift.

Ele preenche a lacuna entre Modelos de Linguagem de Grande Porte (LLMs) ou assistentes de IA (como os do Claude, Cursor ou aplicativos personalizados) e seu data warehouse Redshift, permitindo acesso e interação de dados seguros e padronizados. Isso permite que os usuários consultem dados, entendam a estrutura do banco de dados e realizem operações de monitoramento/diagnóstico usando linguagem natural ou prompts orientados por IA.

Este servidor é para desenvolvedores, analistas de dados ou equipes que buscam integrar capacidades de LLM diretamente com seu ambiente de dados Amazon Redshift de maneira estruturada e segura.

Sumário

Recursos

  • ✨ Conexão Segura com Redshift (via Data API): Conecta-se ao seu cluster Amazon Redshift usando a AWS Redshift Data API via Boto3, utilizando o AWS Secrets Manager para credenciais gerenciadas com segurança por meio de variáveis de ambiente.
  • 🔍 Descoberta de Esquemas: Expõe recursos MCP para listar esquemas e tabelas dentro de um esquema especificado.
  • 📊 Metadados e Estatísticas: Fornece uma ferramenta (handle_inspect_table) para coletar metadados detalhados da tabela, estatísticas (como tamanho, contagens de linhas, skew, obsolescência de estatísticas) e status de manutenção.
  • 📝 Execução de Consultas Somente Leitura: Oferece uma ferramenta MCP segura (handle_execute_ad_hoc_query) para executar consultas SELECT arbitrárias no banco de dados Redshift, permitindo a recuperação de dados com base em solicitações do LLM.
  • 📈 Análise de Desempenho de Consultas: Inclui uma ferramenta (handle_diagnose_query_performance) para recuperar e analisar o plano de execução, métricas e dados históricos de um ID de consulta específico.
  • 🔍 Inspeção de Tabelas: Fornece uma ferramenta (handle_inspect_table) para realizar uma inspeção abrangente de uma tabela, incluindo design, armazenamento, saúde e uso.
  • 🩺 Verificação de Saúde do Cluster: Oferece uma ferramenta (handle_check_cluster_health) para realizar uma avaliação de saúde básica ou completa do cluster usando várias consultas de diagnóstico.
  • 🔒 Diagnóstico de Locks: Fornece uma ferramenta (handle_diagnose_locks) para identificar e relatar contenção de locks e sessões bloqueadas atuais.
  • 📊 Monitoramento de Carga de Trabalho: Inclui uma ferramenta (handle_monitor_workload) para analisar padrões de carga de trabalho do cluster em uma janela de tempo, cobrindo WLM, consultas mais pesadas e uso de recursos.
  • 📝 Recuperação de DDL: Oferece uma ferramenta (handle_get_table_definition) para recuperar a saída do SHOW TABLE (DDL) para uma tabela especificada.
  • 🛡️ Sanitização de Entrada: Utiliza consultas parametrizadas por meio do cliente Boto3 Redshift Data API quando aplicável para mitigar riscos de injeção de SQL.
  • 🧩 Interface MCP Padronizada: Segue a especificação Model Context Protocol para integração perfeita com clientes compatíveis (ex.: Claude Desktop, Cursor IDE, aplicativos personalizados).

Pré-requisitos

Software:

  • Python 3.10+
  • uv (gerenciador de pacotes recomendado) ou pip

Infraestrutura e Acesso:

  • Acesso a um cluster Amazon Redshift.
  • Uma conta AWS com permissões para usar a Redshift Data API (redshift-data:*) e acessar o segredo especificado no Secrets Manager (secretsmanager:GetSecretValue).
  • Uma conta de usuário do Redshift cujas credenciais estejam armazenadas no AWS Secrets Manager. Esse usuário precisa das permissões necessárias dentro do Redshift para executar as ações habilitadas por este servidor (ex.: CONNECT no banco de dados, SELECT nas tabelas de destino, SELECT nas visualizações de sistema relevantes, como pg_class, pg_namespace, svv_all_schemas, svv_tables, `svv_table_info``). Recomenda-se fortemente o uso de uma função com o princípio do menor privilégio. Consulte Considerações de Segurança.

Credenciais:

Os detalhes de conexão do seu Redshift são gerenciados via AWS Secrets Manager, e o servidor se conecta usando a Redshift Data API. Você precisa de:

  • O identificador do cluster Redshift.
  • O nome do banco de dados dentro do cluster.
  • O ARN do segredo no AWS Secrets Manager contendo as credenciais do banco de dados (nome de usuário e senha).
  • A região AWS onde o cluster e o segredo estão localizados.
  • Opcionalmente, um nome de perfil AWS se você não estiver usando credenciais/região padrão.

Esses detalhes serão configurados por meio de variáveis de ambiente, conforme detalhado na seção Configuração.

Instalação

Instalar a partir do PyPI (Recomendado)

A maneira mais fácil de instalar o Redshift Utils MCP Server é diretamente do PyPI:

# Using pip
pip install redshift-utils-mcp

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

Instalar a partir do Código-fonte

Alternativamente, você pode instalar a partir do repositório de código-fonte:

# 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 .

Configuração

Defina as Variáveis de Ambiente: Este servidor requer as seguintes variáveis de ambiente para se conectar ao seu cluster Redshift via AWS Data API. Você pode defini-las diretamente no seu shell, usando um arquivo de serviço do systemd, um arquivo de ambiente Docker ou criando um arquivo .env no diretório raiz do projeto (se você estiver usando uma ferramenta como uv ou python-dotenv que suporte carregamento a partir de .env).

Exemplo usando export no 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

Exemplo de arquivo .env (consulte .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

Tabela de Variáveis Obrigatórias:

Nome da VariávelObrigatóriaDescriçãoExemplo de Valor
REDSHIFT_CLUSTER_IDSimIdentificador do seu cluster Redshift.my-redshift-cluster
REDSHIFT_DATABASESimO nome do banco de dados ao qual conectar.mydatabase
REDSHIFT_SECRET_ARNSimARN do AWS Secrets Manager para as credenciais do Redshift.arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret-abcdef
AWS_REGIONSimRegião AWS para a Data API e o Secrets Manager.us-east-1
AWS_DEFAULT_REGIONNãoAlternativa ao AWS_REGION para especificar a região AWS.us-west-2
AWS_PROFILENãoNome do perfil AWS a ser usado a partir do seu arquivo de credenciais (~/.aws/...).my-redshift-profile

Nota: Certifique-se de que as credenciais AWS usadas pelo Boto3 (via ambiente, perfil ou função IAM) tenham permissões para acessar o REDSHIFT_SECRET_ARN especificado e usar a Redshift Data API (redshift-data:*).

Uso

Após a instalação, você pode executar o servidor diretamente da linha de comando:

# If installed from PyPI
redshift-utils-mcp

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

Conectando com o Claude Desktop / Anthropic Console:

Adicione o seguinte bloco de configuração ao seu arquivo 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"
      }
  }
}

Conectando com o Claude Code CLI:

Use o CLI do Claude para adicionar a configuração do 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

Conectando com o Cursor IDE:

  1. Inicie o servidor MCP localmente usando as instruções na seção Uso / Início Rápido.
  2. No Cursor, abra a Paleta de Comandos (Cmd/Ctrl + Shift + P).
  3. Digite "Connect to MCP Server" ou navegue até as configurações do MCP.
  4. Adicione uma nova conexão de servidor.
  5. Escolha o tipo de transporte stdio.
  6. Digite o comando e os argumentos necessários para iniciar o seu servidor (uvx run redshift_utils_mcp). Certifique-se de que todas as variáveis de ambiente necessárias estejam disponíveis para o comando que será executado.
  7. O Cursor deve detectar o servidor e suas ferramentas/recursos disponíveis.

Recursos MCP Disponíveis

Padrão de URI do RecursoDescriçãoExemplo de URI
/scripts/{script_path}Recupera o conteúdo bruto de um arquivo de script SQL do diretório sql_scripts do servidor./scripts/health/disk_usage.sql
redshift://schemasLista todos os esquemas definidos pelo usuário acessíveis no banco de dados conectado.redshift://schemas
redshift://wlm/configurationRecupera os detalhes atuais da configuração do Workload Management (WLM).redshift://wlm/configuration
redshift://schema/{schema_name}/tablesLista todas as tabelas e visualizações acessíveis dentro do {schema_name} especificado.redshift://schema/public/tables

Substitua {script_path} e {schema_name} pelos valores reais ao fazer solicitações. A acessibilidade de esquemas/tabelas depende das permissões concedidas ao usuário do Redshift configurado via REDSHIFT_SECRET_ARN.

Ferramentas MCP Disponíveis

Nome da FerramentaDescriçãoParâmetros Chave (Obrigatório*)Exemplo de Invocação
handle_check_cluster_healthRealiza uma avaliação de saúde do cluster Redshift usando um 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 contenção de locks ativa e sessões bloqueadas no cluster.min_wait_seconds (opcional)use_mcp_tool("redshift-admin", "handle_diagnose_locks", {"min_wait_seconds": 10})
handle_diagnose_query_performanceAnalisa o desempenho de execução de uma consulta específica, incluindo plano, métricas e dados históricos.query_id*use_mcp_tool("redshift-admin", "handle_diagnose_query_performance", {"query_id": 12345})
handle_execute_ad_hoc_queryExecuta uma consulta SQL arbitrária fornecida pelo usuário via Redshift Data API. Projetado como uma saída de emergência.sql_query*use_mcp_tool("redshift-admin", "handle_execute_ad_hoc_query", {"sql_query": "SELECT ..."})
handle_get_table_definitionRecupera a instrução DDL (Data Definition Language) (SHOW TABLE) para uma tabela específica.schema_name, table_nameuse_mcp_tool("redshift-admin", "handle_get_table_definition", {"schema_name": "public", ...})
handle_inspect_tableRecupera informações detalhadas sobre uma tabela Redshift específica, cobrindo design, armazenamento, saúde e uso.schema_name, table_nameuse_mcp_tool("redshift-admin", "handle_inspect_table", {"schema_name": "analytics", ...})
handle_monitor_workloadAnalisa padrões de carga de trabalho do cluster em um intervalo de tempo especificado usando vários scripts de diagnóstico.time_window_days (opcional), top_n_queries (opcional)use_mcp_tool("redshift-admin", "handle_monitor_workload", {"time_window_days": 7})

A FAZER

  • Melhorar Opções de Prompt
  • Adicionar suporte para mais métodos de credenciais
  • Adicionar suporte para Redshift Serverless

Referências