ClickHouse MCP 서버 프로젝트 상세 소개

개요

ClickHouse MCP 서버는 ClickHouse 공식 개발팀에서 개발한 Model Context Protocol (MCP) 서버 구현체로, AI 어시스턴트(예: Claude)에게 ClickHouse 데이터베이스와의 안전한 연결 및 상호 작용 기능을 제공하는 데 특화되어 있습니다. 이 프로젝트는 표준화된 MCP 프로토콜을 통해 AI 어시스턴트가 SQL 쿼리를 실행하고, 데이터베이스 구조를 관리하며, 실시간 데이터 분석을 수행할 수 있도록 합니다.

MCP (Model Context Protocol)는 AI 애플리케이션에 안전하고 표준화된 외부 서비스 통합 방식을 제공하기 위한 개방형 표준입니다. 이 서버를 통해 사용자는 AI 어시스턴트가 ClickHouse 데이터베이스에 직접 액세스하여 지능형 데이터 쿼리 및 분석을 수행할 수 있도록 할 수 있습니다.

핵심 기능

1. SQL 쿼리 실행 (run_select_query)

• 기능 설명: ClickHouse 클러스터에서 SQL 쿼리 실행
• 보안 메커니즘: 모든 쿼리는 readonly = 1 모드에서 실행되어 데이터 보안 보장
• 입력 매개변수:
  • sql (문자열): 실행할 SQL 쿼리문
• 사용 시나리오: 데이터 검색, 통계 분석, 보고서 생성

2. 데이터베이스 관리 (list_databases)

• 기능 설명: ClickHouse 클러스터의 모든 데이터베이스 목록 표시
• 용도: 데이터베이스 구조 탐색, 권한 검증
• 반환 내용: 액세스 가능한 데이터베이스 목록

3. 테이블 관리 (list_tables)

• 기능 설명: 지정된 데이터베이스의 모든 테이블 목록 표시
• 입력 매개변수:
  • database (문자열): 데이터베이스 이름
• 용도: 테이블 구조 탐색, 데이터 모델 이해

구성 및 배포

Claude Desktop 통합

macOS 구성 경로

~/Library/Application Support/Claude/claude_desktop_config.json

Windows 구성 경로

%APPDATA%/Claude/claude_desktop_config.json

기본 구성 예시

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.13",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_PORT": "<clickhouse-port>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
      }
    }
  }
}

환경 변수 구성

필수 변수

• CLICKHOUSE_HOST: ClickHouse 서버 호스트 이름
• CLICKHOUSE_USER: 인증 사용자 이름
• CLICKHOUSE_PASSWORD: 인증 비밀번호

선택적 변수

• CLICKHOUSE_PORT: 포트 번호
  • 기본값: HTTPS 활성화 시 8443, 비활성화 시 8123
• CLICKHOUSE_SECURE: HTTPS 연결 활성화/비활성화
  • 기본값: "true"
• CLICKHOUSE_VERIFY: SSL 인증서 검증 활성화/비활성화
  • 기본값: "true"
• CLICKHOUSE_CONNECT_TIMEOUT: 연결 시간 초과 (초)
  • 기본값: "30"
• CLICKHOUSE_SEND_RECEIVE_TIMEOUT: 송신/수신 시간 초과 (초)
  • 기본값: "300"
• CLICKHOUSE_DATABASE: 기본 연결 데이터베이스
  • 기본값: 없음 (서버 기본값 사용)

사용 시나리오

1. ClickHouse SQL 연습장 구성

{
  "env": {
    "CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
    "CLICKHOUSE_PORT": "8443",
    "CLICKHOUSE_USER": "demo",
    "CLICKHOUSE_PASSWORD": "",
    "CLICKHOUSE_SECURE": "true",
    "CLICKHOUSE_VERIFY": "true"
  }
}

2. 로컬 개발 환경 구성

# .env 파일 구성
CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse
CLICKHOUSE_SECURE=false
CLICKHOUSE_VERIFY=false

3. ClickHouse Cloud 구성

CLICKHOUSE_HOST=your-instance.clickhouse.cloud
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=your-password
# 안전 기본 설정 사용

개발 및 테스트

환경 준비

# 의존성 설치
uv sync

# 가상 환경 활성화
source .venv/bin/activate

# 개발 서버 시작
mcp dev mcp_clickhouse/mcp_server.py

테스트 절차

# 개발 의존성 설치
uv sync --all-extras --dev

# 코드 검사
uv run ruff check .

# 테스트 서비스 시작
docker compose up -d test_services

# 테스트 실행
uv run pytest tests

보안 고려 사항

데이터베이스 권한 관리

• 최소 권한 원칙: MCP 데이터베이스 사용자는 필요한 최소 권한만 보유해야 함
• 관리자 계정 회피: 기본 또는 관리자 사용자 사용 엄금
• 읽기 전용 모드: 모든 쿼리는 읽기 전용 모드에서 실행되어 데이터 수정 방지

네트워크 보안

• HTTPS 연결: 프로덕션 환경에서는 HTTPS 활성화 권장
• 인증서 검증: SSL 인증서 검증 활성화로 연결 보안 확보
• 시간 초과 설정: 연결 및 쿼리 시간 초과를 합리적으로 설정하여 리소스 점유 방지

기술 특성

호환성

• Python 버전: Python 3.13 지원
• 의존성 관리: uv를 사용한 패키지 관리
• 컨테이너화: Docker 배포 지원
• 크로스 플랫폼: macOS, Windows, Linux 지원

성능 최적화

• 연결 풀: 효율적인 데이터베이스 연결 관리
• 시간 초과 제어: 구성 가능한 연결 및 쿼리 시간 초과
• 비동기 지원: 비동기 쿼리 실행 지원

요약

ClickHouse MCP 서버 프로젝트는 AI 어시스턴트와 ClickHouse 데이터베이스 간에 안전하고 효율적인 다리를 놓습니다. 표준화된 MCP 프로토콜을 통해 AI 어시스턴트가 복잡한 데이터베이스 구조를 이해하고 조작하며, 정교한 SQL 쿼리를 실행하고, 실시간 데이터 통찰력을 제공할 수 있도록 합니다.

주요 장점

1. 공식 지원: ClickHouse 공식 팀에서 유지 관리하여 호환성 및 안정성 보장
2. 보안 설계: 내장된 읽기 전용 모드 및 권한 제어로 데이터 보안 보호
3. 쉬운 통합: 표준화된 MCP 프로토콜로 AI 애플리케이션 통합 간소화
4. 유연한 구성: 로컬 개발부터 클라우드 프로덕션까지 다양한 배포 시나리오 지원
5. 개발 친화적: 완벽한 개발 도구 체인 및 테스트 프레임워크

적용 시나리오

• 데이터 분석: AI 어시스턴트가 복잡한 데이터 분석 작업을 지원하도록 함
• 비즈니스 인텔리전스: 자동화된 보고서 생성 및 데이터 통찰력
• 실시간 모니터링: AI와 결합하여 시스템 및 비즈니스 지표 모니터링
• 데이터 탐색: 자연어 쿼리를 통해 데이터베이스 구조 및 내용 탐색

이 프로젝트는 AI와 데이터베이스 통합의 새로운 방향을 제시하며, 개발자에게 AI 어시스턴트가 엔터프라이즈급 데이터 리소스를 진정으로 이해하고 조작할 수 있도록 하는 강력하고 안전한 도구를 제공합니다.