Redshift MCP Server

이 MCP(Model Context Protocol) 서버는 Claude Desktop 및 기타 MCP 호환 클라이언트에서 사용할 수 있도록 Amazon Redshift 데이터베이스에 대한 안전한 읽기 전용 액세스를 제공합니다. 지능형 브리지 역할을 하여 AI 어시스턴트가 데이터 웨어하우스에서 직접 독립적으로 탐색, 이해, 인사이트를 추출할 수 있게 해줍니다.

✨ 주요 기능

• 10가지 특화 도구: 데이터 탐색, 메타데이터 추출, 쿼리, 내보내기를 위한 완전한 도구 모음.

• 동적 구성: .env를 통해 완전히 구성 가능(허용 목록, 행 제한, 연결 매개변수).

• 전송 모드: stdio(Claude Desktop과 같은 로컬 클라이언트용) 및 sse(원격 연결용 HTTP 기반 Server-Sent Events)를 모두 지원.

• 연결 캐싱: Redshift에 대한 단일 장기 유지 상태 확인 연결을 통한 효율적인 연결 관리.

• 엔터프라이즈 보안:

  • 엄격한 읽기 전용 SQL 검증.

  • 스키마 허용 목록(AI를 사전 승인된 스키마로 제한).

  • 데이터베이스 성능 보호를 위한 쿼리 및 내보내기 행 수 상한.

• SSH 터널 지원: 통합 sshtunnel을 통해 프라이빗 VPC Redshift 클러스터에 원활하게 연결.

Related MCP server: safedb-mcp

🛠️ 사용 가능한 MCP 도구

데이터 탐색 및 내비게이션

1. get_allowed_schemas: 서버의 스키마 액세스 구성(허용 목록, 기본 스키마, 제한)을 반환합니다.

2. list_schemas: 데이터베이스에서 액세스 가능한 스키마를 탐색합니다(구성된 허용 목록으로 필터링).

3. list_tables: 스키마의 모든 테이블을 나열합니다. 허용 목록에 있는 스키마만 액세스할 수 있습니다.

4. describe_table: 테이블의 열 이름, 데이터 유형, null 허용 여부, 기본값을 가져옵니다.

5. search_columns: 허용된 스키마의 모든 테이블에서 이름이 키워드와 일치하는(대소문자 구분 없음) 열을 검색합니다.

데이터 분석 및 추출

6. sample_data: 데이터 탐색을 위해 테이블에서 행 샘플을 빠르게 반환합니다.

7. table_row_count: COUNT(*)를 사용하여 테이블의 정확한 행 수를 가져옵니다.

8. query_data: 읽기 전용 SELECT 쿼리를 실행합니다. 서버 구성에 따라 결과를 자동으로 래핑하고 제한합니다.

9. explain_query: 실행 전에 성능을 이해하기 위해 쿼리의 EXPLAIN 계획을 표시합니다.

10. export_to_csv: 더 높은 전용 행 제한(MAX_EXPORT_ROWS)으로 쿼리 결과를 CSV 형식으로 내보냅니다.

🚀 설정 및 설치

1. 종속성 설치

# Clone the repository
git clone <repository-url>
cd redshift-mcp-server

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

2. 환경 구성

예제 환경 파일을 복사하고 자격 증명으로 편집합니다:

cp .env.example .env

.env 파일을 편집하여 Redshift 연결 및 서버 제한을 구성합니다:

# --- Redshift Connection ---
RS_HOST=your-cluster.region.redshift.amazonaws.com
RS_DB=your_database_name
RS_USER=your_readonly_user
RS_PASS=your_password
RS_PORT=5439

# --- Security & Limits ---
ALLOWED_SCHEMAS=gold_capsaai,report_capsaai
DEFAULT_SCHEMA=gold_capsaai
MAX_ROWS=500
MAX_EXPORT_ROWS=5000

# --- SSH Tunnel (For Private VPCs) ---
SSH_TUNNEL=false
# If true, provide SSH_HOST, SSH_USER, SSH_KEY_FILE, etc.

3. 서버 시작

모드 1: stdio(기본값) MCP 클라이언트(예: Claude Desktop)가 동일한 머신에서 실행 중일 때 가장 적합합니다.

python server.py

모드 2: sse(HTTP) HTTP 또는 터널을 통해 서버에 원격으로 액세스할 때 가장 적합합니다.

# Start SSE on port 8000
python server.py --sse --host 0.0.0.0 --port 8000

🔌 서버에 연결

옵션 A: 로컬 Claude Desktop(stdio)

Claude Desktop이 서버와 동일한 머신에서 실행 중인 경우 Claude Desktop 구성 파일을 편집합니다:

• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "redshift": {
      "command": "/absolute/path/to/redshift-mcp-server/.venv/bin/python",
      "args": ["/absolute/path/to/redshift-mcp-server/server.py"]
    }
  }
}

옵션 B: 원격 연결(SSE + IDE)

서버가 원격 EC2 인스턴스에서 실행 중인 경우 --sse 모드로 서버를 시작합니다.

직접 SSE 연결을 지원하는 IDE(예: Cline이 있는 VS Code)의 경우:

1. 새 MCP 서버를 추가합니다.

2. 전송 유형을 SSE로 설정합니다.

3. URL을 사용합니다: http://<EC2-IP>:8000/sse(또는 터널 URL).

🧪 테스트 및 검증

저장소에는 포괄적인 테스트 스위트와 진단 도구가 포함되어 있습니다:

• client.py: 10개 도구 모두에 대해 종단 간 스모크 테스트를 실행하는 CLI 클라이언트.

• test_connection.py: 기본 연결 검증.

• test_restricted_access.py: 스키마 보안 제한이 올바르게 작동하는지 확인.

• monitor_mcp.sh: 자동 재시작, 상태 확인, 로깅을 갖춘 프로덕션 준비 모니터링.

🏗️ 아키텍처

graph TB
    subgraph "Client Layer"
        CD["Claude Desktop / MCP Client"]
    end
    
    subgraph "MCP Server Layer"
        MCP["FastMCP Server"]
        CONFIG["config.py / .env"]
        VALIDATION["SQL & Schema Validation"]
    end
    
    subgraph "Network Layer"  
        SSH["SSH Tunnel<br/>(Optional)"]
        CONN["Connection Cache"]
    end
    
    subgraph "Database Layer"
        RS["Amazon Redshift"]
        SCHEMA["Allowed Schemas"]
    end
    
    CD -->|"JSON-RPC (stdio/sse)"| MCP
    MCP --> CONFIG
    MCP --> VALIDATION
    VALIDATION --> CONN
    CONN --> SSH
    SSH --> RS
    RS --> SCHEMA

🔐 보안 고려 사항

• 읽기 전용: _validate_read_only_sql 래퍼는 쿼리를 SELECT 및 EXPLAIN 문으로 엄격히 제한합니다.

• 제한 엔진: _apply_limit의 정규식 파싱을 통해 이중 LIMIT 구문 버그를 방지하여 대규모 테이블 스캔이 .env 임계값에서 제한되도록 보장합니다.

• 스키마 격리: AI는 쉼표로 구분된 ALLOWED_SCHEMAS 목록 외부의 테이블을 보거나 쿼리할 수 없습니다.

• 자격 증명 안전 유지: .env 또는 .json 구성 파일을 버전 관리에 커밋하지 마십시오. 기본적으로 .gitignore에서 무시됩니다.