ClickHouse MCP 서버 설정

ClickHouse MCP 서버를 사용하면 호환되는 AI 어시스턴트가 데이터베이스를 탐색하고, 테이블을 확인하며, ClickHouse에서 SQL 쿼리를 실행할 수 있습니다. 이 가이드에서는 uv를 사용해 로컬 stdio 서버를 구성하고 주요 MCP 클라이언트에 연결하는 방법을 설명합니다.

서버는 기본적으로 읽기 전용 쿼리만 허용합니다. AI 어시스턴트에 필요한 권한만 부여된 전용 ClickHouse 사용자를 사용하고, default 사용자나 관리자 사용자는 사용하지 마십시오.

다음 절차에서는 Claude Desktop을 사용한 설정을 안내합니다. 이 가이드에서 다루는 다른 클라이언트에도 동일한 ClickHouse 연결 정보를 사용합니다.

사전 요구 사항

시작하기 전에 다음을 준비하십시오.

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 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에서 설정을 열고 개발자를 선택한 다음 구성 편집을 선택합니다. 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 CLI에서 server를 추가합니다:

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 데스크톱 앱에서는 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를 입력하여 연결된 서버를 확인하세요.

현재 프로젝트의 .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 설정을 열어 서버가 활성화되어 있는지 확인하십시오.

~/.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.

클라이언트에서 최초 도구 호출에 대한 승인을 요청할 수 있습니다. 액세스를 허용하기 전에 모든 요청을 검토하십시오.

문제 해결

클라이언트가 uv를 찾을 수 없다고 보고하는 경우, 명령어나 구성의 uv를 절대 경로로 바꾸십시오. 해당 경로를 찾으려면 macOS 또는 Linux에서 which uv를, Windows에서 where uv를 실행하십시오.

추가 연결 설정, 선택적 chDB 지원, HTTP 전송 및 인증에 대해서는 mcp-clickhouse README를 참조하십시오.