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 클러스터 식별자입니다. |
|
| 예 | 연결할 데이터베이스의 이름입니다. |
|
| 예 | Redshift 자격 증명에 대한 AWS Secrets Manager ARN입니다. |
|
| 예 | Data API 및 Secrets Manager를 위한 AWS 지역입니다. |
|
| 아니요 | AWS 지역을 지정하기 위한 |
|
| 아니요 | 자격 증명 파일(~/.aws/...)에서 사용할 AWS 프로필 이름입니다. |
|
참고: 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에 연결:
사용법/빠른 시작 섹션의 지침을 사용하여 MCP 서버를 로컬로 시작합니다.
커서에서 명령 팔레트를 엽니다(Cmd/Ctrl + Shift + P).
"MCP 서버에 연결"을 입력하거나 MCP 설정으로 이동합니다.
새로운 서버 연결을 추가합니다.
stdio전송 유형을 선택하세요.서버를 시작하는 데 필요한 명령과 인수를 입력하세요(
uvx run redshift_utils_mcp). 실행하는 명령에서 필요한 환경 변수를 사용할 수 있는지 확인하세요.커서는 서버와 사용 가능한 도구/리소스를 감지해야 합니다.
사용 가능한 MCP 리소스
리소스 URI 패턴 | 설명 | 예제 URI |
| 서버의 |
|
| 연결된 데이터베이스에서 접근 가능한 모든 사용자 정의 스키마를 나열합니다. |
|
| 현재 워크로드 관리(WLM) 구성 세부 정보를 검색합니다. |
|
| 지정된 |
|
요청 시 {script_path} 와 {schema_name} 실제 값으로 바꾸세요. 스키마/테이블의 접근성은 REDSHIFT_SECRET_ARN 통해 구성된 Redshift 사용자에게 부여된 권한에 따라 달라집니다.
사용 가능한 MCP 도구
도구 이름 | 설명 | 주요 매개변수(필수*) | 예제 호출 |
| 일련의 진단 SQL 스크립트를 사용하여 Redshift 클러스터의 상태 평가를 수행합니다. |
|
|
| 클러스터에서 활성 잠금 경합과 차단 세션을 식별합니다. |
|
|
| 계획, 메트릭, 과거 데이터를 포함하여 특정 쿼리의 실행 성능을 분석합니다. |
|
|
| Redshift Data API를 통해 사용자가 제공한 임의의 SQL 쿼리를 실행합니다. 비상구로 설계되었습니다. |
|
|
| 특정 테이블에 대한 DDL(데이터 정의 언어) 문( |
|
|
| 설계, 저장소, 상태 및 사용법을 포함하여 특정 Redshift 테이블에 대한 자세한 정보를 검색합니다. |
|
|
| 다양한 진단 스크립트를 사용하여 지정된 기간 동안 클러스터 작업 부하 패턴을 분석합니다. |
|
|
할 일
[ ] 프롬프트 옵션 개선
[ ] 더 많은 자격 증명 방법에 대한 지원 추가
[ ] 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) 파일을 참조하세요.
참고문헌
이 프로젝트는 모델 컨텍스트 프로토콜 사양 에 크게 의존합니다.
Model Context Protocol 에서 제공하는 공식 MCP SDK를 사용하여 구축되었습니다.
AWS SDK for Python( Boto3 )을 활용하여 Amazon Redshift Data API 와 상호 작용합니다.
많은 진단 SQL 스크립트는 훌륭한 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