Skip to main content
Glama
redshift-utils-mcp

redshift-utils-mcp

Redshift Utils MCP 서버

개요

이 프로젝트는 Amazon Redshift 데이터베이스와 상호 작용하도록 특별히 설계된 MCP(Model Context Protocol) 서버를 구현합니다.

대규모 언어 모델(LLM) 또는 AI 어시스턴트(Claude, Cursor 또는 사용자 지정 애플리케이션 등)와 Redshift 데이터 웨어하우스 간의 격차를 해소하여 안전하고 표준화된 데이터 액세스 및 상호 작용을 지원합니다. 이를 통해 사용자는 자연어 또는 AI 기반 프롬프트를 사용하여 데이터를 쿼리하고, 데이터베이스 구조를 이해하고, 작업을 모니터링/진단할 수 있습니다.

이 서버는 LLM 기능을 체계적이고 안전한 방식으로 Amazon Redshift 데이터 환경과 직접 통합하려는 개발자, 데이터 분석가 또는 팀을 위한 것입니다.

Related MCP server: Redshift MCP Server

목차

특징

  • ✨ 보안 Redshift 연결(데이터 API를 통해): Boto3를 통해 AWS Redshift Data API를 사용하여 Amazon Redshift 클러스터에 연결하고, 환경 변수를 통해 안전하게 관리되는 자격 증명에 AWS Secrets Manager를 활용합니다.

  • 🔍 스키마 검색: 지정된 스키마 내의 스키마와 테이블을 나열하기 위한 MCP 리소스를 공개합니다.

  • 📊 메타데이터 및 통계: 자세한 테이블 메타데이터, 통계(크기, 행 수, 비대칭, 통계 부실 여부 등), 유지 관리 상태를 수집하는 도구( handle_inspect_table )를 제공합니다.

  • 📝 읽기 전용 쿼리 실행: Redshift 데이터베이스에 대해 임의의 SELECT 쿼리를 실행하여 LLM 요청에 따라 데이터를 검색할 수 있는 안전한 MCP 도구( handle_execute_ad_hoc_query )를 제공합니다.

  • 📈 쿼리 성능 분석: 특정 쿼리 ID에 대한 실행 계획, 메트릭 및 과거 데이터를 검색하고 분석하는 도구( handle_diagnose_query_performance )가 포함되어 있습니다.

  • 🔍 테이블 검사: 디자인, 보관, 상태, 사용 등을 포함하여 테이블에 대한 포괄적인 검사를 수행하는 도구( handle_inspect_table )를 제공합니다.

  • 🩺 클러스터 상태 점검: 다양한 진단 쿼리를 사용하여 클러스터의 기본 또는 전체 상태 평가를 수행하는 도구( handle_check_cluster_health )를 제공합니다.

  • 🔒 잠금 진단: 현재 잠금 경합 및 차단 세션을 식별하고 보고하는 도구( handle_diagnose_locks )를 제공합니다.

  • 📊 워크로드 모니터링: WLM, 주요 쿼리, 리소스 사용량을 포함하여 특정 시간 창에 대한 클러스터 워크로드 패턴을 분석하는 도구( handle_monitor_workload )가 포함되어 있습니다.

  • 📝 DDL 검색: 지정된 테이블에 대한 SHOW TABLE 출력(DDL)을 검색하는 도구( handle_get_table_definition )를 제공합니다.

  • 🛡️ 입력 정리: 해당되는 경우 Boto3 Redshift Data API 클라이언트를 통해 매개변수화된 쿼리를 활용하여 SQL 주입 위험을 완화합니다.

  • 🧩 표준화된 MCP 인터페이스: 호환 가능한 클라이언트(예: Claude Desktop, Cursor IDE, 사용자 정의 애플리케이션)와의 원활한 통합을 위해 모델 컨텍스트 프로토콜 사양을 준수합니다.

필수 조건

소프트웨어:

  • 파이썬 3.8 이상

  • uv (추천 패키지 관리자)

  • Git(저장소 복제용)

인프라 및 접근성:

  • Amazon Redshift 클러스터에 액세스합니다.

  • Redshift Data API( redshift-data:* )를 사용하고 지정된 Secrets Manager 비밀( secretsmanager:GetSecretValue )에 액세스할 수 있는 권한이 있는 AWS 계정입니다.

  • AWS Secrets Manager에 자격 증명이 저장된 Redshift 사용자 계정. 이 사용자는 이 서버에서 활성화된 작업(예: 데이터베이스에 CONNECT , 대상 테이블에 SELECT , pg_class , pg_namespace , svv_all_schemas , svv_tables , `svv_table_info`와 같은 관련 시스템 뷰에 대한 SELECT )을 수행하기 위해 Redshift 내에서 필요한 권한이 필요합니다. 최소 권한 원칙에 따라 역할을 사용하는 것이 좋습니다. 보안 고려 사항을 참조하세요.

신임장:

Redshift 연결 세부 정보는 AWS Secrets Manager를 통해 관리되며, 서버는 Redshift Data API를 사용하여 연결합니다. 다음이 필요합니다.

  • Redshift 클러스터 식별자.

  • 클러스터 내의 데이터베이스 이름입니다.

  • 데이터베이스 자격 증명(사용자 이름 및 비밀번호)이 포함된 AWS Secrets Manager 비밀번호의 ARN입니다.

  • 클러스터와 비밀이 있는 AWS 지역입니다.

  • 선택적으로 기본 자격 증명/지역을 사용하지 않는 경우 AWS 프로필 이름을 입력합니다.

이러한 세부 정보는 구성 섹션에 자세히 설명된 대로 환경 변수를 통해 구성됩니다.

구성

환경 변수 설정: 이 서버는 AWS Data API를 통해 Redshift 클러스터에 연결하기 위해 다음 환경 변수가 필요합니다. 셸에서 직접 설정하거나, systemd 서비스 파일이나 Docker 환경 파일을 사용하거나, 프로젝트의 루트 디렉터리에 .env 파일을 생성하여 설정할 수 있습니다( .env 파일에서 로딩을 지원하는 uv 또는 python-dotenv 와 같은 도구를 사용하는 경우).

셸 내보내기를 사용한 예:

지엑스피1

예시 .env 파일( .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

필수 변수 표:

변수 이름

필수의

설명

예시 값

REDSHIFT_CLUSTER_ID

예

Redshift 클러스터 식별자입니다.

my-redshift-cluster

REDSHIFT_DATABASE

예

연결할 데이터베이스의 이름입니다.

mydatabase

REDSHIFT_SECRET_ARN

예

Redshift 자격 증명에 대한 AWS Secrets Manager ARN입니다.

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

AWS_REGION

예

Data API 및 Secrets Manager를 위한 AWS 지역입니다.

us-east-1

AWS_DEFAULT_REGION

아니요

AWS 지역을 지정하기 위한 AWS_REGION 의 대안입니다.

us-west-2

AWS_PROFILE

아니요

자격 증명 파일(~/.aws/...)에서 사용할 AWS 프로필 이름입니다.

my-redshift-profile

참고: Boto3에서 사용하는 AWS 자격 증명(환경, 프로필 또는 IAM 역할을 통해)에 지정된 REDSHIFT_SECRET_ARN 에 액세스하고 Redshift Data API( redshift-data:* )를 사용할 수 있는 권한이 있는지 확인하세요.

용법

Claude Desktop/Anthropic Console에 연결:

다음 구성 블록을 mcp.json 파일에 추가하세요. 설치 방법 및 설정에 따라 command , args , env , workingDirectory 조정하세요.

{
  "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"
      }
  }
}

커서 IDE에 연결:

  1. 사용법/빠른 시작 섹션의 지침을 사용하여 MCP 서버를 로컬로 시작합니다.

  2. 커서에서 명령 팔레트를 엽니다(Cmd/Ctrl + Shift + P).

  3. "MCP 서버에 연결"을 입력하거나 MCP 설정으로 이동합니다.

  4. 새로운 서버 연결을 추가합니다.

  5. stdio 전송 유형을 선택하세요.

  6. 서버를 시작하는 데 필요한 명령과 인수를 입력하세요( uvx run redshift_utils_mcp ). 실행하는 명령에서 필요한 환경 변수를 사용할 수 있는지 확인하세요.

  7. 커서는 서버와 사용 가능한 도구/리소스를 감지해야 합니다.

사용 가능한 MCP 리소스

리소스 URI 패턴

설명

예제 URI

/scripts/{script_path}

서버의 sql_scripts 디렉토리에서 SQL 스크립트 파일의 원시 내용을 검색합니다.

/scripts/health/disk_usage.sql

redshift://schemas

연결된 데이터베이스에서 접근 가능한 모든 사용자 정의 스키마를 나열합니다.

redshift://schemas

redshift://wlm/configuration

현재 워크로드 관리(WLM) 구성 세부 정보를 검색합니다.

redshift://wlm/configuration

redshift://schema/{schema_name}/tables

지정된 {schema_name} 내에서 접근 가능한 모든 테이블과 뷰를 나열합니다.

redshift://schema/public/tables

요청 시 {script_path} 와 {schema_name} 실제 값으로 바꾸세요. 스키마/테이블의 접근성은 REDSHIFT_SECRET_ARN 통해 구성된 Redshift 사용자에게 부여된 권한에 따라 달라집니다.

사용 가능한 MCP 도구

도구 이름

설명

주요 매개변수(필수*)

예제 호출

handle_check_cluster_health

일련의 진단 SQL 스크립트를 사용하여 Redshift 클러스터의 상태 평가를 수행합니다.

level (선택 사항), time_window_days (선택 사항)

use_mcp_tool("redshift-admin", "handle_check_cluster_health", {"level": "full"})

handle_diagnose_locks

클러스터에서 활성 잠금 경합과 차단 세션을 식별합니다.

min_wait_seconds (선택 사항)

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

handle_diagnose_query_performance

계획, 메트릭, 과거 데이터를 포함하여 특정 쿼리의 실행 성능을 분석합니다.

query_id *

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

handle_execute_ad_hoc_query

Redshift Data API를 통해 사용자가 제공한 임의의 SQL 쿼리를 실행합니다. 비상구로 설계되었습니다.

sql_query *

use_mcp_tool("redshift-admin", "handle_execute_ad_hoc_query", {"sql_query": "SELECT ..."})

handle_get_table_definition

특정 테이블에 대한 DDL(데이터 정의 언어) 문( SHOW TABLE )을 검색합니다.

schema_name , table_name

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

handle_inspect_table

설계, 저장소, 상태 및 사용법을 포함하여 특정 Redshift 테이블에 대한 자세한 정보를 검색합니다.

schema_name , table_name

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

handle_monitor_workload

다양한 진단 스크립트를 사용하여 지정된 기간 동안 클러스터 작업 부하 패턴을 분석합니다.

time_window_days (선택 사항), top_n_queries (선택 사항)

use_mcp_tool("redshift-admin", "handle_monitor_workload", {"time_window_days": 7})

할 일

  • [ ] 프롬프트 옵션 개선

  • [ ] 더 많은 자격 증명 방법에 대한 지원 추가

  • [ ] Redshift Serverless에 대한 지원 추가

기여하다

기여를 환영합니다! 다음 지침을 따라주세요.

문제 찾기/제보: GitHub Issues 페이지에서 기존 버그나 기능 요청을 확인하세요. 필요한 경우 새 이슈를 개설해 주세요.

MCP 서버를 통해 데이터베이스 액세스를 제공할 때는 보안이 매우 중요합니다. 다음 사항을 고려하세요.

🔒 자격 증명 관리: 이 서버는 Redshift Data API를 통해 AWS Secrets Manager를 사용하는데, 이는 자격 증명을 환경 변수나 구성 파일에 직접 저장하는 것보다 더 안전한 방법입니다. Boto3에서 사용하는 AWS 자격 증명(환경, 프로필 또는 IAM 역할을 통해)이 안전하게 관리되고 필요한 최소한의 권한을 가지고 있는지 확인하십시오. AWS 자격 증명이나 보안 정보가 포함된 .env 파일을 버전 관리 시스템에 커밋하지 마십시오.

🛡️ 최소 권한 원칙: AWS Secrets Manager에 자격 증명이 있는 Redshift 사용자에게 서버의 의도된 기능에 필요한 최소한의 권한만 부여합니다. 예를 들어, 읽기 권한만 필요한 경우, 필요한 스키마/테이블에는 CONNECT 및 SELECT 권한만 부여하고 필요한 시스템 뷰에는 SELECT 권한을 부여합니다. admin 나 클러스터 슈퍼유저와 같이 권한이 높은 사용자는 사용하지 마십시오.

제한된 Redshift 사용자 생성 및 권한 관리에 대한 지침은 공식 문서( https://docs.aws.amazon.com/redshift/latest/mgmt/security.html )를 참조하세요.

특허

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 (LICENSE) 파일을 참조하세요.

참고문헌

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