메인 콘텐츠로 건너뛰기
이 가이드에서는 uv를 사용해 Claude Desktop을 ClickHouse MCP 서버와 함께 설정하고 ClickHouse 예시 데이터셋에 연결하는 방법을 설명합니다.
1

​
uv 설치

이 가이드의 지침을 따르려면 uv를 설치해야 합니다. uv를 사용하지 않으려면 다른 패키지 관리자를 사용하도록 MCP 서버 구성을 수정해야 합니다.
2

​
Claude Desktop 다운로드

Claude Desktop 앱도 설치해야 하며, Claude Desktop 웹사이트에서 다운로드할 수 있습니다.
3

​
ClickHouse MCP 서버 구성

Claude Desktop 설치를 완료했다면, 이제 ClickHouse MCP 서버를 구성할 차례입니다. 이 작업은 Claude Desktop 설정 파일을 통해 수행할 수 있습니다.이 파일을 찾으려면 먼저 설정 페이지로 이동한 뒤(Mac에서는 Cmd+,) 왼쪽 메뉴에서 Developer 탭을 클릭하십시오. 그러면 다음 화면이 표시되며, 여기서 Edit config 버튼을 클릭해야 합니다:그러면 설정 파일(claude_desktop_config.json)이 들어 있는 디렉터리로 이동합니다. 이 파일을 처음 열면 다음과 같은 내용이 들어 있을 가능성이 높습니다:
{
  "mcpServers": {}
}
mcpServers 딕셔너리는 키로 MCP 서버 이름을 받고, 값으로 구성 옵션 딕셔너리를 받습니다. 예를 들어, ClickHouse Playground에 연결하는 ClickHouse MCP 서버 구성은 다음과 같습니다:
{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.10",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
        "CLICKHOUSE_PORT": "8443",
        "CLICKHOUSE_USER": "demo",
        "CLICKHOUSE_PASSWORD": "",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
      }
    }
  }
}
구성을 업데이트한 후에는 변경 사항이 적용되도록 Claude Desktop을 다시 시작해야 합니다.
uv를 설치한 방식에 따라 Claude Desktop을 다시 시작할 때 다음 오류가 발생할 수 있습니다:
MCP mcp-clickhouse: spawn uv ENOENT
이 경우 command를 uv의 전체 경로로 수정해야 합니다. 예를 들어 Cargo를 통해 설치했다면 /Users/<username>/.cargo/bin/uv입니다.
4

​
ClickHouse MCP 서버 사용하기

Claude Desktop을 다시 시작한 후 Search and tools 아이콘을 클릭하면 ClickHouse MCP 서버를 찾을 수 있습니다:
그런 다음 모든 도구 또는 일부 도구를 비활성화할지 선택할 수 있습니다.이제 Claude에 질문해 ClickHouse MCP 서버를 사용하게 할 준비가 되었습니다. 예를 들어 SQL playground에서 가장 흥미로운 데이터셋은 무엇인가요?라고 물어볼 수 있습니다.Claude는 MCP 서버의 각 도구를 처음 호출할 때 해당 도구 사용을 승인할지 확인하도록 요청합니다:아래에서는 ClickHouse MCP 서버에 대한 일부 도구 호출이 포함된 대화의 일부를 볼 수 있습니다:
마지막 수정일 2026년 6월 19일