ClickHouse MCP Server — Claude Code MCP 서버

ClickHouse(컬럼형 OLAP DB)에 연결해 자연어 쿼리와 스키마 탐색을 제공하는 공식 MCP 서버.

ClickHouse MCP Server는 ClickHouse(컬럼형 OLAP 데이터베이스)에 Claude Code 같은 MCP 클라이언트를 연결해 주는 ClickHouse 공식 MCP 서버입니다. AI 에이전트가 자연어로 표현한 분석 의도를 SQL 질의로 옮겨 실행하고, 데이터베이스·테이블·컬럼 등 스키마를 탐색하도록 도구를 제공합니다. 이를 통해 사람이 매번 콘솔에 접속해 쿼리를 손으로 작성하지 않아도, 대화 흐름 안에서 데이터를 조회하고 결과를 받아볼 수 있습니다.

이 서버가 푸는 핵심 문제는 "대규모 분석 데이터에 대한 탐색적 질의의 진입 장벽"입니다. ClickHouse는 로그·이벤트·텔레메트리·웹 트래픽 같은 대용량 시계열/분석 데이터를 빠르게 집계하는 데 강점이 있는데, 막상 스키마가 크고 테이블이 많으면 어떤 컬럼이 있고 어떻게 조인해야 하는지 파악하는 데 시간이 듭니다. MCP 서버는 스키마 탐색 도구로 구조를 먼저 보여주고, 그 맥락 위에서 AI가 적절한 쿼리를 만들어 실행하도록 해 분석 반복(iteration) 속도를 높입니다.

주요 기능은 (1) ClickHouse 인스턴스 연결(호스트/포트/사용자/비밀번호 환경변수 기반), (2) 데이터베이스·테이블·컬럼 스키마 조회, (3) SQL 질의 실행과 결과 반환입니다. 정확한 도구 목록·동작·읽기 전용 여부 등 세부 사항은 버전에 따라 다를 수 있으므로 공식 저장소(github.com/ClickHouse/mcp-clickhouse) 문서 확인을 권장합니다.

누가 쓰면 좋은가: ClickHouse를 운영 중인 데이터 엔지니어·분석가, 로그/이벤트 분석 파이프라인을 다루는 백엔드 개발자, 그리고 AI 어시스턴트를 통해 애드혹(ad-hoc) 데이터 질의를 자주 하고 싶은 팀에 적합합니다. 설치는 uv 기반으로 진행하며 연결 정보를 환경변수로 주입하는 방식입니다(정확한 명령은 공식 문서 참조).

언제 쓰나

ClickHouse에 쌓인 로그·이벤트·트래픽 등 대용량 분석 데이터를 AI와의 대화 흐름에서 바로 조회·집계하고 싶을 때, 또는 테이블이 많아 스키마 파악과 쿼리 작성에 시간이 들 때 적합합니다. 애드혹 분석, 데이터 탐색, 리포트 초안 작성 보조에 유용합니다. 트랜잭션 위주 OLTP 워크로드나 ClickHouse를 쓰지 않는 환경에는 맞지 않습니다.

설치

uv 기반 설치 후 CLICKHOUSE_HOST/PORT/USER/PASSWORD 환경변수로 연결. 정확한 명령은 공식 문서 참조.

uv 기반으로 설치한 뒤 CLICKHOUSE_HOST/PORT/USER/PASSWORD 환경변수로 대상 인스턴스를 지정해 연결합니다. 정확한 패키지명·실행 명령·지원 도구 범위는 버전에 따라 달라질 수 있으니 공식 저장소(github.com/ClickHouse/mcp-clickhouse) 문서 확인을 권장합니다. 사내 ClickHouse라면 방화벽/네트워크 접근 권한과 TLS 설정도 함께 확인하세요. MCP 클라이언트(Claude Code 등) 설정 파일에 서버를 등록해야 도구가 노출됩니다.

필요 키(직접 발급, 플레이스홀더): CLICKHOUSE_HOST, CLICKHOUSE_USER, CLICKHOUSE_PASSWORD

보안 주의

CLICKHOUSE_HOST·CLICKHOUSE_USER·CLICKHOUSE_PASSWORD 등 DB 접속 자격증명을 다루므로 비밀번호는 환경변수/시크릿 매니저로만 주입하고 코드·로그·커밋에 노출하지 마세요. AI가 SQL을 생성·실행하는 구조이므로, 가능하면 권한이 제한된 읽기 전용(read-only) 계정과 최소 권한 원칙을 적용해 DROP/TRUNCATE/DELETE 등 파괴적 쿼리 위험을 차단하는 것을 권장합니다. 운영 DB 직접 연결은 신중히 하고, 외부에서 들어온 텍스트(테이블 내용·컬럼명)가 프롬프트 인젝션 경로가 될 수 있으니 자동 실행 범위를 통제하세요.

자주 묻는 질문

ClickHouse MCP Server는 무엇을 하나요?

ClickHouse(컬럼형 OLAP DB)에 MCP 클라이언트를 연결해, 자연어 의도를 SQL 질의로 실행하고 데이터베이스·테이블·컬럼 스키마를 탐색하도록 도구를 제공하는 공식 MCP 서버입니다.

운영 데이터베이스에 바로 연결해도 되나요?

가능하지만 권장 방식은 읽기 전용·최소 권한 계정 사용입니다. AI가 SQL을 생성·실행하므로 파괴적 쿼리 위험을 줄이려면 권한을 제한하고 자동 실행 범위를 통제하세요. 자세한 설정은 공식 문서 확인을 권장합니다.

어떻게 설치하나요?

uv 기반으로 설치한 뒤 CLICKHOUSE_HOST/PORT/USER/PASSWORD 환경변수로 연결합니다. 정확한 명령과 패키지명은 버전에 따라 다를 수 있어 공식 저장소 문서를 참고하세요.