ClickHouse MCP 서버 설정하기

ClickHouse MCP 서버는 호환되는 AI 어시스턴트가 ClickHouse의 데이터베이스 탐색, 테이블 검사, SQL 쿼리 실행을 할 수 있게 해줘요. 이 가이드에서는 uv로 로컬 stdio 서버를 구성하고 주요 MCP 클라이언트에 연결하는 방법을 설명해요. 서버는 기본적으로 읽기 전용 쿼리만 허용해요. 어시스턴트가 필요한 권한만 가진 전용 ClickHouse 사용자를 사용하고, 기본 또는 관리 사용자는 사용하지 마세요. 아래 워크스루는 Claude Desktop으로 설정을 보여주지만, 같은 ClickHouse 연결 정보가 이 가이드에서 다루는 다른 클라이언트에도 적용돼요.

출처: 문서

본문

준비 사항 (Prerequisites)

시작하기 전에:

uv를 설치해요.
사용하려는 MCP 클라이언트를 설치해요.
ClickHouse 서비스의 호스트 이름, 사용자 이름, 비밀번호를 준비해요.

아래 예제들은 이런 자리 표시자 값을 사용해요.

환경 변수	값
`CLICKHOUSE_HOST`	`your-clickhouse-host`
`CLICKHOUSE_USER`	`your-clickhouse-user`
`CLICKHOUSE_PASSWORD`	`your-clickhouse-password`

이들을 자신의 연결 정보로 바꿔주세요. ClickHouse Cloud 서비스의 경우 서버는 기본적으로 8443 포트에서 HTTPS를 사용해요. 평문 HTTP를 사용하는 자체 관리 서비스라면 CLICKHOUSE_SECURE=false도 설정하고, 필요하면 CLICKHOUSE_PORT=8123을 설정해요.

MCP 클라이언트 구성하기

Claude Code
Claude Desktop
Codex
ChatGPT
Cursor
Windsurf

Claude Code: 터미널에서 다음 명령을 실행해요.

claude mcp add \
  --transport stdio \
  --env CLICKHOUSE_HOST=your-clickhouse-host \
  --env CLICKHOUSE_USER=your-clickhouse-user \
  --env CLICKHOUSE_PASSWORD=your-clickhouse-password \
  --scope user \
  mcp-clickhouse -- \
  uv run --with mcp-clickhouse --python 3.10 mcp-clickhouse

claude mcp list를 실행해 연결을 확인하거나, Claude Code에서 /mcp를 입력해 서버와 도구를 검사해요.

Claude Desktop: Settings를 열고 Developer를 선택한 뒤 Edit config를 선택해요. claude_desktop_config.json에 다음 서버를 추가해요.

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.10",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "your-clickhouse-host",
        "CLICKHOUSE_USER": "your-clickhouse-user",
        "CLICKHOUSE_PASSWORD": "your-clickhouse-password"
      }
    }
  }
}

파일을 저장하고 Claude Desktop을 재시작해요. 채팅 작성기에서 Connectors를 열어 mcp-clickhouse가 사용 가능한지 확인해요.

Codex: Codex CLI에서 서버를 추가해요.

codex mcp add mcp-clickhouse \
  --env CLICKHOUSE_HOST=your-clickhouse-host \
  --env CLICKHOUSE_USER=your-clickhouse-user \
  --env CLICKHOUSE_PASSWORD=your-clickhouse-password \
  -- uv run --with mcp-clickhouse --python 3.10 mcp-clickhouse

codex mcp list를 실행해 연결을 확인하거나, Codex 터미널 UI에서 /mcp를 입력해요. Codex CLI, Codex IDE 확장, ChatGPT 데스크톱 앱은 ~/.codex/config.toml의 MCP 구성을 공유해요.

ChatGPT: ChatGPT 데스크톱 앱은 Codex 호스트용 로컬 MCP 서버를 구성해요. 이 구성은 Codex CLI 및 Codex IDE 확장과 공유됩니다. ChatGPT 데스크톱 앱에서:

Settings를 연 다음 MCP servers를 선택해요.
Add server를 선택하고 STDIO를 골라요.
이름으로 mcp-clickhouse, 명령으로 uv를 입력해요.
그 순서대로 run, --with, mcp-clickhouse, --python, 3.10, mcp-clickhouse를 인자로 추가해요.
CLICKHOUSE_HOST, CLICKHOUSE_USER, CLICKHOUSE_PASSWORD에 연결 정보를 추가해요.
서버를 저장하고 앱을 재시작해요.

앱이 재시작되면 Codex를 열고 작성기에서 /mcp를 입력해 연결된 서버를 검사해요.

이 단계들은 ChatGPT 데스크톱 앱에서 Codex용 로컬 stdio 서버를 구성해요. 반면 ChatGPT 웹은 플러그인이 제공하는 원격 MCP 기반 도구를 사용해요. ChatGPT 웹에서 ClickHouse 도구를 사용하려면 ClickHouse Cloud의 Remote MCP server를 참고해요.

Cursor: 현재 프로젝트의 .cursor/mcp.json 또는 전역 Cursor MCP 구성에 다음 서버를 추가해요.

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.10",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "your-clickhouse-host",
        "CLICKHOUSE_USER": "your-clickhouse-user",
        "CLICKHOUSE_PASSWORD": "your-clickhouse-password"
      }
    }
  }
}

Cursor를 새로고침한 뒤 MCP 설정을 열어 서버가 활성화됐는지 확인해요.

Windsurf: ~/.codeium/windsurf/mcp_config.json에 다음 서버를 추가해요.

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.10",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "your-clickhouse-host",
        "CLICKHOUSE_USER": "your-clickhouse-user",
        "CLICKHOUSE_PASSWORD": "your-clickhouse-password"
      }
    }
  }
}

Windsurf를 새로고침한 뒤 MCP 설정을 열어 서버가 활성화됐는지 확인해요.

연결 확인하기

클라이언트가 mcp-clickhouse가 연결됐다고 보고하면 다음을 요청해보세요.

List the databases available in ClickHouse, then show me the tables in one of them.

클라이언트가 첫 도구 호출을 승인하도록 요청할 수도 있어요. 접근 권한을 부여하기 전에 모든 요청을 검토해요.

문제 해결 (Troubleshooting)

클라이언트가 uv를 찾지 못한다고 보고하면 명령 또는 구성에서 uv를 절대 경로로 바꿔요. macOS/Linux에서는 which uv, Windows에서는 where uv를 실행해 그 경로를 찾아요. 추가 연결 설정, 선택적 chDB 지원, HTTP 전송, 인증은 mcp-clickhouse README를 참고해요.

ClickHouse MCP 서버 설정하기