CopilotKit과 ClickHouse MCP 서버로 AI 에이전트 빌드하기

ClickHouse에 저장된 데이터를 사용해 에이전틱(agentic) 애플리케이션을 빌드하는 예제예요. ClickHouse MCP 서버로 데이터를 쿼리하고 차트를 생성하며, CopilotKit으로 UI와 채팅 인터페이스를 구성해요.

출처: 문서

본문

이것은 ClickHouse에 저장된 데이터를 사용해 에이전틱 애플리케이션을 빌드하는 예제예요. ClickHouse MCP 서버를 사용해 ClickHouse에서 데이터를 쿼리하고 그 데이터를 기반으로 차트를 생성해요. CopilotKit은 UI를 빌드하고 사용자에게 채팅 인터페이스를 제공하는 데 사용돼요.

예제 코드 이 예제의 코드는 examples 리포지토리에서 찾을 수 있어요.

전제 조건 (Prerequisites)

Node.js >= 20.14.0
uv >= 0.1.0

의존성 설치하기

프로젝트를 로컬에 클론하세요: git clone https://github.com/ClickHouse/examples 그리고 ai/mcp/copilotkit 디렉토리로 이동하세요. 이 섹션을 건너뛰고 ./install.sh 스크립트를 실행해 의존성을 설치해도 돼요. 수동으로 의존성을 설치하려면 아래 지침을 따르세요.

의존성 수동 설치

의존성 설치하기: npm install을 실행해 node 의존성을 설치하세요.
mcp-clickhouse 설치하기: external이라는 새 폴더를 만들고 그 안에 mcp-clickhouse 리포지토리를 클론하세요.

mkdir -p external
git clone https://github.com/ClickHouse/mcp-clickhouse external/mcp-clickhouse

Python 의존성을 설치하고 fastmcp cli 도구를 추가하세요.

cd external/mcp-clickhouse
uv sync
uv add fastmcp

애플리케이션 구성하기

env.example 파일을 .env로 복사하고 편집해서 ANTHROPIC_API_KEY를 제공하세요.

자체 LLM 사용하기

Anthropic 대신 다른 LLM 제공자를 사용하고 싶다면, Copilotkit 런타임을 수정해 다른 LLM 어댑터를 사용할 수 있어요. 여기에서 지원되는 제공자 목록을 확인할 수 있어요.

자체 ClickHouse 클러스터 사용하기

기본적으로 이 예제는 ClickHouse 데모 클러스터에 연결하도록 구성되어 있어요. 다음 환경 변수들을 설정해 자체 ClickHouse 클러스터를 사용할 수도 있어요:

CLICKHOUSE_HOST
CLICKHOUSE_PORT
CLICKHOUSE_USER
CLICKHOUSE_PASSWORD
CLICKHOUSE_SECURE

애플리케이션 실행하기

npm run dev를 실행해 개발 서버를 시작하세요. 다음과 같은 프롬프트로 에이전트를 테스트할 수 있어요:

"지난 10년간 맨체스터의 가격 추이를 보여줘."

브라우저에서 http://localhost:3000을 열면 결과를 볼 수 있어요.

CopilotKit과 ClickHouse MCP 서버로 AI 에이전트 빌드하기