ClickHouse/mcp-clickhouse

해결하는 문제

이 프로젝트는 AI 어시스턴트(예: Claude Desktop)가 ClickHouse 데이터베이스와 직접 상호 작용할 수 있도록 하는 Model Context Protocol (MCP) 서버를 제공합니다. LLM과 ClickHouse에 저장된 구조화된 데이터 간의 격차를 해소하여, 사용자가 수동으로 파일을 내보내거나 모든 쿼리를 직접 작성할 필요 없이 AI가 데이터를 쿼리, 탐색, 분석할 수 있게 합니다.

작동 방식

이 서버는 특정 ClickHouse 도구를 MCP 호환 클라이언트에 노출하는 중개자 역할을 합니다. 원격 ClickHouse 클러스터에 연결하거나 ETL 프로세스 없이 파일이나 URL에서 데이터를 쿼리하기 위한 임베디드 ClickHouse 엔진인 chDB를 사용하는 두 가지 작동 모드를 지원합니다.

주요 기능은 다음과 같습니다.

• 쿼리 실행: SQL 인젝션을 방지하고 복잡한 유형을 처리하기 위해 명명된 매개변수를 지원하는 SQL 쿼리를 실행합니다.
• 데이터베이스 탐색: 데이터베이스와 테이블을 나열(페이지네이션 및 필터링 포함)하여 AI가 스키마를 이해하도록 돕습니다.
• 쿼리 검사: DESCRIBE를 사용하여 결과 스키마를 확인하고 EXPLAIN ESTIMATE를 사용하여 실행 전에 쿼리의 리소스 비용을 예측합니다.
• 보안: 기본적으로 읽기 전용 모드를 구현하고 HTTP/SSE 전송을 위해 여러 인증 방법(정적 Bearer 토큰 또는 OAuth/OIDC)을 제공합니다.

대상 사용자

• 데이터 분석가 및 엔지니어: AI를 사용하여 ClickHouse의 대규모 데이터 세트를 탐색하려는 사람.
• AI 애플리케이션 개발자: LLM 에이전트가 ClickHouse 데이터베이스에서 실시간 데이터 검색을 수행할 수 있도록 하려는 사람.
• DevOps 엔지니어: ClickHouse 데이터 액세스를 MCP 기반 AI 생태계에 통합해야 하는 사람.

주요 특징

• 이중 엔진 지원: 전체 ClickHouse 클러스터와 임베디드 chDB 엔진 모두에서 작동합니다.
• 안전한 탐색: 기본 읽기 전용 액세스와 비용이 많이 드는 스캔을 방지하기 위한 쿼리 비용 추정 도구.
• 안전한 매개변수화: {name:Type} 자리 표시자를 사용하여 안전하고 정확한 데이터 바인딩을 제공합니다.
• 엔터프라이즈급 인증: FastMCP를 통해 다양한 OIDC 공급자를 지원하여 프로덕션 배포에 적합합니다.