레드시프트-유틸-MCP

Redshift Utils MCP 서버

개요

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

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

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

특징

✨ 보안 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에 연결:

사용법/빠른 시작 섹션의 지침을 사용하여 MCP 서버를 로컬로 시작합니다.
커서에서 명령 팔레트를 엽니다(Cmd/Ctrl + Shift + P).
"MCP 서버에 연결"을 입력하거나 MCP 설정으로 이동합니다.
새로운 서버 연결을 추가합니다.
stdio 전송 유형을 선택하세요.
서버를 시작하는 데 필요한 명령과 인수를 입력하세요( uvx run redshift_utils_mcp ). 실행하는 명령에서 필요한 환경 변수를 사용할 수 있는지 확인하세요.
커서는 서버와 사용 가능한 도구/리소스를 감지해야 합니다.

사용 가능한 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) 파일을 참조하세요.

참고문헌

이 프로젝트는 모델 컨텍스트 프로토콜 사양 에 크게 의존합니다.
Model Context Protocol 에서 제공하는 공식 MCP SDK를 사용하여 구축되었습니다.
AWS SDK for Python( Boto3 )을 활용하여 Amazon Redshift Data API 와 상호 작용합니다.
많은 진단 SQL 스크립트는 훌륭한 awslabs/amazon-redshift-utils 저장소에서 가져왔습니다.

redshift-utils-mcp

Integrations

Redshift Utils MCP 서버

개요

목차

특징

필수 조건

구성

용법

Claude Desktop/Anthropic Console에 연결:

커서 IDE에 연결:

사용 가능한 MCP 리소스

사용 가능한 MCP 도구

할 일

기여하다

특허

참고문헌

Tools

Related Resources

Related MCP Servers

replicate-flux-mcp

ygocdb-mcp

mcp-metricoolofficial

Status Observer MCP