Ollama와 함께 ClickHouse MCP 서버 설정하기

이 가이드에서는 Ollama와 함께 ClickHouse MCP 서버를 사용하는 방법을 설명해요.

출처: 문서

본문

1. Ollama 설치

Ollama는 자신의 머신에서 대규모 언어 모델(LLM)을 실행하기 위한 라이브러리예요. 다양한 모델을 지원하며 사용하기 쉬워요. 다운로드 페이지에서 Mac, Windows, Linux용 Ollama를 받을 수 있어요. Ollama를 실행하면 백그라운드에서 로컬 서버가 시작되고, 이를 통해 모델을 실행할 수 있어요. 또는 ollama serve로 서버를 수동으로 실행할 수도 있어요. 설치 후 아래처럼 모델을 머신으로 내려받을 수 있어요.

ollama pull qwen3:8b

없다면 모델을 로컬 머신으로 가져와요. 다운로드되면 아래처럼 모델을 실행할 수 있어요.

ollama run qwen3:8b

도구 지원이 있는 모델만 MCP 서버와 함께 동작해요.

다운로드한 모델 목록은 아래처럼 확인할 수 있어요.

ollama ls

NAME                       ID              SIZE      MODIFIED
qwen3:latest               500a1f067a9f    5.2 GB    3 days ago

다운로드한 모델에 대한 자세한 정보는 다음 명령으로 볼 수 있어요.

ollama show qwen3

  Model
    architecture        qwen3
    parameters          8.2B
    context length      40960
    embedding length    4096
    quantization        Q4_K_M

  Capabilities
    completion
    tools

  Parameters
    repeat_penalty    1
    stop              "<|im_start|>"
    stop              "<|im_end|>"
    temperature       0.6
    top_k             20
    top_p             0.95

  License
    Apache License
    Version 2.0, January 2004

이 출력에서 기본 qwen3 모델이 80억 개가 살짝 넘는 파라미터를 가졌음을 알 수 있어요.

2. MCPHost 설치

이 글을 쓰는 시점(2025년 7월)에는 Ollama를 MCP 서버와 함께 사용하는 네이티브 기능이 없어요. 하지만 MCPHost를 사용하면 Ollama 모델을 MCP 서버에서 실행할 수 있어요. MCPHost는 Go 애플리케이션이므로 머신에 Go가 설치되어 있어야 해요. 그런 다음 다음 명령으로 MCPHost를 설치할 수 있어요.

go install github.com/mark3labs/mcphost@latest

바이너리는 ~/go/bin 아래에 설치되므로 이 디렉터리가 PATH에 있는지 확인해야 해요.

3. ClickHouse MCP 서버 구성하기

MCPHost로 MCP 서버를 YAML 또는 JSON 파일에 구성할 수 있어요. MCPHost는 홈 디렉터리에서 다음 순서로 구성 파일을 찾아요.

.mcphost.yml 또는 .mcphost.json (권장)
.mcp.yml 또는 .mcp.json (하위 호환성)

표준 MCP 구성 파일과 비슷한 구문을 사용해요. 다음은 ~/.mcphost.json 파일에 저장할 ClickHouse MCP 서버 구성 예시예요.

{
  "mcpServers": {
    "mcp-ch": {
      "type": "local",
      "command": ["uv",
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.10",
        "mcp-clickhouse"
      ]
    }
  }
}

표준 MCP 구성 파일과의 주요 차이는 type을 지정해야 한다는 것이에요. type은 MCP 서버가 사용하는 전송 유형을 나타내요.

local → stdio 전송
remote → streamable 전송
builtin → inprocess 전송

또한 다음 환경 변수를 구성해야 해요.

export CLICKHOUSE_HOST=sql-clickhouse.clickhouse.com
export CLICKHOUSE_USER=demo
export CLICKHOUSE_PASSWORD=""

이론상으로는 이 변수들을 MCP 구성 파일의 environment 키 아래 제공해야 하지만, 그렇게 하면 동작하지 않는 것을 확인했어요.

4. MCPHost 실행하기

ClickHouse MCP 서버를 구성한 뒤 다음 명령으로 MCPHost를 실행할 수 있어요.

mcphost --model ollama:qwen3

또는 특정 구성 파일을 사용하려면:

mcphost --model ollama:qwen3 --config ~/.mcphost.json

--model을 제공하지 않으면 MCPHost는 환경 변수에서 ANTHROPIC_API_KEY를 찾아 anthropic:claude-sonnet-4-20250514 모델을 사용해요.

다음과 같은 출력이 보일 거예요.

  ┃                                                                                     ┃
  ┃  Model loaded: ollama (qwen3)                                                       ┃
  ┃   MCPHost System (09:52)                                                            ┃
  ┃                                                                                     ┃

  ┃                                                                                     ┃
  ┃  Model loaded successfully on GPU                                                   ┃
  ┃   MCPHost System (09:52)                                                            ┃
  ┃                                                                                     ┃

  ┃                                                                                     ┃
  ┃  Loaded 3 tools from MCP servers                                                    ┃
  ┃   MCPHost System (09:52)                                                            ┃
  ┃                                                                                     ┃

  Enter your prompt (Type /help for commands, Ctrl+C to quit, ESC to cancel generation)

/servers 명령으로 MCP 서버 목록을 볼 수 있어요.

  ┃                                                                                      ┃
  ┃  ## Configured MCP servers                                                           ┃
  ┃                                                                                      ┃
  ┃  1. mcp-ch                                                                           ┃
  ┃   MCPHost System (10:00)                                                             ┃
  ┃

그리고 /tools로 사용 가능한 도구를 나열할 수 있어요.

  ┃  ## Available Tools                                                                  ┃
  ┃                                                                                      ┃
  ┃  1. mcp-ch__list_databases                                                           ┃
  ┃  2. mcp-ch__list_tables                                                              ┃
  ┃  3. mcp-ch__run_select_query

이제 모델에게 ClickHouse SQL 플레이그라운드에 있는 데이터베이스/테이블에 대해 질문할 수 있어요. 경험상 더 작은 모델(기본 qwen3는 80억 파라미터)을 사용할 때는 원하는 작업을 더 구체적으로 지시해야 해요. 예를 들어 어떤 테이블을 바로 조회하라고 시키기보다 데이터베이스와 테이블을 명시적으로 나열하라고 요청해야 해요. 더 큰 모델(예: qwen3:14b)을 사용하면 이 문제를 부분적으로 완화할 수 있지만, 일반 소비자 하드웨어에서는 더 느리게 실행돼요.

Ollama와 함께 ClickHouse MCP 서버 설정하기