본문으로 바로가기
본문으로 바로가기

Claude Desktop와 함께 ClickHouse MCP 서버 사용하기

이 가이드는 uv를 사용하여 Claude Desktop을 ClickHouse MCP 서버와 함께 설정하고 ClickHouse 예시 데이터셋에 연결하는 방법을 설명합니다.

uv 설치하기​

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

Claude Desktop 다운로드하기​

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

ClickHouse MCP 서버 구성하기​

Claude Desktop를 설치한 후에는 이제 ClickHouse MCP server를 구성해야 합니다. 이는 Claude Desktop 설정 파일을 통해 수행할 수 있습니다.

이 파일을 찾으려면 먼저 설정 페이지로 이동합니다(Mac에서는 Cmd+, 사용), 그런 다음 왼쪽 메뉴에서 Developer 탭을 클릭합니다. 그러면 다음과 같은 화면이 표시되며, 여기에서 Edit config 버튼을 클릭합니다:

Claude Desktop 설정 파일

해당 버튼을 클릭하면 설정 파일(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가 됩니다.

ClickHouse MCP 서버 사용하기​

Claude Desktop을 다시 시작한 후에는 Search and tools 아이콘을 클릭하여 ClickHouse MCP 서버를 찾을 수 있습니다:

Find MCP servers

그런 다음 모든 도구 또는 일부 도구를 비활성화할지 선택할 수 있습니다.

이제 Claude가 ClickHouse MCP 서버를 사용하게 하는 질문을 할 준비가 되었습니다. 예를 들어, SQL playground에서 가장 흥미로운 dataset은 무엇인가요?라고 물어볼 수 있습니다.

Claude는 MCP 서버의 각 도구가 처음 호출될 때 해당 도구 사용을 확인해 달라고 요청합니다:

Give permission to use the list_databases tool

아래에서는 ClickHouse MCP 서버에 대한 일부 도구 호출이 포함된 대화의 한 부분을 확인할 수 있습니다:

Claude conversation