MCP 문서 관리

메뉴

홈
문서 목록
관리자 로그인

문서 정보

최종 수정일:
2025-05-12 20:33
태그:
#MCP #데이터베이스 #분석 #SQL #써드파티

링크된 문서

역링크

ClickHouse MCP 서버

ClickHouse MCP 서버

ClickHouse MCP 서버는 ClickHouse 데이터베이스를 위한 Model Context Protocol(MCP) 서버 구현체입니다. 이 서버를 통해 LLM(대규모 언어 모델)은 ClickHouse 데이터베이스에 저장된 대용량 데이터를 쿼리하고 분석할 수 있습니다.

주요 기능

  • SQL 쿼리 실행: ClickHouse 클러스터에서 안전한 읽기 전용 SQL 쿼리 실행
  • 데이터베이스 관리: 클러스터의 모든 데이터베이스 및 테이블 목록 조회
  • 안전한 접근: 모든 쿼리는 readonly = 1 설정으로 실행되어 데이터 안전성 보장
  • 다양한 연결 옵션: 로컬 ClickHouse 인스턴스, ClickHouse Cloud, SQL 플레이그라운드 지원

제공 도구

ClickHouse MCP 서버는 다음과 같은 도구를 제공합니다:

쿼리 도구

  • run_select_query: ClickHouse 클러스터에서 SQL 쿼리 실행
  • 입력: sql (string) - 실행할 SQL 쿼리
  • 모든 ClickHouse 쿼리는 안전성을 위해 readonly = 1 설정으로 실행됨

메타데이터 도구

  • list_databases: ClickHouse 클러스터의 모든 데이터베이스 목록 조회
  • list_tables: 특정 데이터베이스의 모든 테이블 목록 조회
  • 입력: database (string) - 테이블을 나열할 데이터베이스 이름

설정 방법

Claude Desktop에 추가하기

Claude Desktop 구성 파일을 엽니다: - macOS: ~/Library/Application Support/Claude/claude_desktop_config.json - Windows: %APPDATA%/Claude/claude_desktop_config.json

다음 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 서비스를 가리키도록 업데이트합니다.

ClickHouse SQL 플레이그라운드 사용하기

ClickHouse SQL 플레이그라운드를 사용하려면 다음 구성을 사용할 수 있습니다:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.13",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
        "CLICKHOUSE_PORT": "8443",
        "CLICKHOUSE_USER": "demo",
        "CLICKHOUSE_PASSWORD": "",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
      }
    }
  }
}

command 항목의 uv를 해당 실행 파일의 절대 경로로 변경하여 서버 시작 시 올바른 버전의 uv가 사용되도록 합니다. 맥에서는 which uv 명령으로 이 경로를 찾을 수 있습니다.

변경 사항을 적용하려면 Claude Desktop을 다시 시작하세요.

환경 변수

ClickHouse 연결을 구성하는 데 다음 환경 변수가 사용됩니다:

필수 변수

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

선택적 변수

  • CLICKHOUSE_PORT: ClickHouse 서버의 포트 번호
  • 기본값: HTTPS가 활성화된 경우 8443, 비활성화된 경우 8123
  • CLICKHOUSE_SECURE: HTTPS 연결 활성화/비활성화
  • 기본값: "true"
  • 비보안 연결의 경우 "false"로 설정
  • CLICKHOUSE_VERIFY: SSL 인증서 확인 활성화/비활성화
  • 기본값: "true"
  • 인증서 확인을 비활성화하려면 "false"로 설정(프로덕션에는 권장하지 않음)
  • CLICKHOUSE_CONNECT_TIMEOUT: 연결 타임아웃(초)
  • 기본값: "30"
  • 연결 타임아웃이 발생하는 경우 이 값을 늘립니다
  • CLICKHOUSE_SEND_RECEIVE_TIMEOUT: 전송/수신 타임아웃(초)
  • 기본값: "300"
  • 장시간 실행 쿼리의 경우 이 값을 늘립니다
  • CLICKHOUSE_DATABASE: 사용할 기본 데이터베이스
  • 기본값: 없음(서버 기본값 사용)
  • 특정 데이터베이스에 자동으로 연결하려면 이 값을 설정합니다

구성 예시

로컬 개발을 위한 Docker:

# 필수 변수
CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse

# 선택적: 로컬 개발을 위한 기본값 재정의
CLICKHOUSE_SECURE=false # 자동으로 포트 8123 사용
CLICKHOUSE_VERIFY=false

ClickHouse Cloud:

# 필수 변수
CLICKHOUSE_HOST=your-instance.clickhouse.cloud
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=your-password

# 선택적: 보안 기본값 사용
# CLICKHOUSE_SECURE=true  # 자동으로 포트 8443 사용
# CLICKHOUSE_DATABASE=your_database

사용 사례

  • 대규모 데이터 분석: 수십억 행의 데이터에 대한 복잡한 분석 쿼리 실행
  • 실시간 대시보드: 실시간 데이터 분석 및 시각화 지원
  • 로그 분석: 대량의 로그 데이터 탐색 및 분석
  • AI 데이터 파이프라인: 머신러닝 및 AI 모델을 위한 데이터 준비 및 처리
  • 비즈니스 인텔리전스: 기업 데이터에 대한 심층 분석 및 보고서 생성

개발 환경 설정

로컬 개발 환경을 설정하려면 다음 단계를 따릅니다:

  1. test-services 디렉토리에서 docker compose up -d를 실행하여 ClickHouse 클러스터를 시작합니다.

  2. 다음 변수를 저장소 루트에 있는 .env 파일에 추가합니다: 

    CLICKHOUSE_HOST=localhost
CLICKHOUSE_PORT=8123
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse

  3. uv sync를 실행하여 종속성을 설치합니다.

  4. 테스트를 위해 mcp dev mcp_clickhouse/mcp_server.py를 실행하여 MCP 서버를 시작합니다.

라이센스

이 서버는 Apache 2.0 라이센스에 따라 라이센스가 부여됩니다.

관련 링크