LibreChat과 함께 ClickHouse MCP 서버 사용하기

이 가이드에서는 Docker로 LibreChat을 ClickHouse MCP 서버와 함께 설정하고 ClickHouse 예제 데이터셋에 연결하는 방법을 설명해요.

출처: 문서

본문

1. Docker 설치

LibreChat과 MCP 서버를 실행하려면 Docker가 필요해요. Docker를 얻으려면:

docker.com 방문
운영체제에 맞는 Docker Desktop 다운로드
운영체제용 지침에 따라 Docker 설치
Docker Desktop을 열고 실행 중인지 확인

자세한 내용은 Docker 문서를 참고해요.

2. LibreChat 저장소 복제하기

터미널(명령 프롬프트, 터미널 또는 PowerShell)을 열고 다음 명령으로 LibreChat 저장소를 복제해요.

git clone https://github.com/danny-avila/LibreChat.git
cd LibreChat

3. .env 파일 만들고 편집하기

예제 구성 파일을 .env.example에서 .env로 복사해요.

cp .env.example .env

.env 파일을 좋아하는 텍스트 편집기로 열어요. OpenAI, Anthropic, AWS bedrock 등 많은 인기 LLM 제공자용 섹션이 보일 거예요. 예를 들어:

#============#
# Anthropic  #
#============#
ANTHROPIC_API_KEY=user_provided
# ANTHROPIC_MODELS=claude-opus-4-20250514,claude-sonnet-4-20250514,claude-3-7-sonnet-20250219,claude-3-5-sonnet-20241022,claude-3-5-haiku-20241022,claude-3-opus-20240229,claude-3-sonnet-20240229,claude-3-haiku-20240307
# ANTHROPIC_REVERSE_PROXY=

user_provided를 사용하려는 LLM 제공자의 API 키로 바꿔요.

로컬 LLM 사용하기 API 키가 없다면 Ollama 같은 로컬 LLM을 사용할 수 있어요. 그 방법은 나중에 “Install Ollama” 단계에서 배워요. 지금은 .env 파일을 수정하지 말고 다음 단계로 진행해요.

4. librechat.yaml 파일 만들기

다음 명령을 실행해 새 librechat.yaml 파일을 만들어요.

cp librechat.example.yaml librechat.yaml

이것이 LibreChat의 주요 구성 파일이 돼요.

5. Docker compose에 ClickHouse MCP 서버 추가하기

LLM이 ClickHouse SQL 플레이그라운드와 상호작용할 수 있도록 LibreChat Docker compose 파일에 ClickHouse MCP 서버를 추가할 거예요. docker-compose.override.yml이라는 파일을 만들고 다음 구성을 추가해요.

services:
  api:
    volumes:
      - ./librechat.yaml:/app/librechat.yaml
  mcp-clickhouse:
    image: mcp/clickhouse
    container_name: mcp-clickhouse
    ports:
      - 8001:8000
    extra_hosts:
      - "host.docker.internal:host-gateway"
    environment:
      - CLICKHOUSE_HOST=sql-clickhouse.clickhouse.com
      - CLICKHOUSE_USER=demo
      - CLICKHOUSE_PASSWORD=
      - CLICKHOUSE_MCP_SERVER_TRANSPORT=sse
      - CLICKHOUSE_MCP_BIND_HOST=0.0.0.0

자신의 데이터를 탐색하고 싶다면, 자신의 ClickHouse Cloud 서비스의 호스트, 사용자 이름, 비밀번호를 사용해도 돼요.

ClickHouse Cloud 시작하기

아직 Cloud 계정이 없다면 오늘 바로 ClickHouse Cloud를 시작해서 $300 크레딧을 받아보세요. 30일 무료 체험 후에는 종량제(pay-as-you-go) 요금제를 계속 사용하거나, 볼륨 기반 할인에 대해 문의할 수 있어요. 자세한 내용은 가격 페이지를 방문해보세요.

6. librechat.yaml에서 MCP 서버 구성하기

librechat.yaml을 열고 파일 끝에 다음 구성을 넣어요.

mcpServers:
  clickhouse-playground:
    type: sse
    url: http://host.docker.internal:8001/sse

이것은 Docker에서 실행 중인 MCP 서버에 LibreChat이 연결하도록 구성해요. 다음 줄을 찾아요.

socialLogins: ['github', 'google', 'discord', 'openid', 'facebook', 'apple', 'saml']

단순화를 위해 지금은 인증 필요 없이 진행할게요.

socialLogins: []

7. Ollama로 로컬 LLM 추가 (선택 사항)

Ollama 설치

Ollama 웹사이트로 이동해 시스템에 Ollama를 설치해요. 설치 후 아래처럼 모델을 실행할 수 있어요.

ollama run qwen3:32b

없다면 모델을 로컬 머신으로 가져와요. 모델 목록은 Ollama 라이브러리를 참고해요.

librechat.yaml에서 Ollama 구성하기

모델이 다운로드되면 librechat.yaml에서 구성해요.

custom:
  - name: "Ollama"
    apiKey: ***
    baseURL: "http://host.docker.internal:11434/v1/"
    models:
      default:
        [
          "qwen3:32b"
        ]
      fetch: false
    titleConvo: true
    titleModel: "current_model"
    summarize: false
    summaryModel: "current_model"
    forcePrompt: false
    modelDisplayLabel: "Ollama"

8. 모든 서비스 시작하기

LibreChat 프로젝트 폴더 루트에서 다음 명령을 실행해 서비스를 시작해요.

docker compose up

모든 서비스가 완전히 실행될 때까지 기다려요.

9. 브라우저에서 LibreChat 열기

모든 서비스가 실행되면 브라우저를 열고 http://localhost:3080/로 이동해요. 아직 계정이 없으면 무료 LibreChat 계정을 만들고 로그인해요. 이제 ClickHouse MCP 서버에 연결된 LibreChat 인터페이스와, 선택한 경우 로컬 LLM이 보일 거예요. 채팅 인터페이스에서 clickhouse-playground를 MCP 서버로 선택해요. 이제 LLM에게 ClickHouse 예제 데이터셋을 탐색하도록 요청할 수 있어요.

What datasets do you have access to?

MCP 서버 옵션이 LibreChat UI에 나타나지 않으면 librechat.yaml 파일에서 올바른 권한이 설정되어 있는지 확인해요. mcpServers 섹션(interface 아래)에서 use가 false로 설정되어 있으면 채팅에서 MCP 선택 드롭다운이 나타나지 않아요.

interface:
  mcpServers:
    use: true
    share: false
    create: false
    public: false

LibreChat과 함께 ClickHouse MCP 서버 사용하기