Hydrolix MCP Server

공식

Hydrolix 시계열 데이터레이크 통합으로 LLM 기반 워크플로우에 스키마 탐색 및 쿼리 기능을 제공합니다.

GitHub

문서

Hydrolix MCP 서버

Hydrolix용 MCP 서버입니다.

빠른 시작

몇 분 안에 시작하고 실행할 수 있습니다. 이 섹션에서는 Claude Desktop과 Claude Code를 다룹니다.

1단계 — 사전 준비 사항

시작하기 전에 다음 사항을 확인하세요:

Hydrolix 자격 증명 — 클러스터 호스트 이름과 사용자 이름/비밀번호 또는 서비스 계정 토큰. 이 정보가 없다면 Hydrolix 관리자에게 문의하세요.
Claude Desktop — claude.ai/download에서 다운로드하세요.

2단계 — MCP 서버 설치

설정에 맞는 방법을 선택하세요:

옵션 A: uv 사용 (권장)

uv는 Python을 자동으로 관리하고 필요 시 mcp-hydrolix를 다운로드하므로 별도의 설치 단계가 필요하지 않습니다. uv가 없다면 설치하세요:

macOS / Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

옵션 B: pip 사용

Python 3.13 이상이 필요합니다. Python을 설치해야 한다면 python.org에서 다운로드하세요.

pip install mcp-hydrolix

3단계 — Claude Desktop 구성

Claude Desktop 구성 파일을 엽니다:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json
"mcpServers" 객체에 다음 항목을 추가합니다 (파일이 아직 없다면 이 내용으로 파일을 생성하세요):

{
  "mcpServers": {
    "mcp-hydrolix": {
      "command": "uvx",
      "args": [
        "--python",
        "3.13",
        "--refresh-package",
        "mcp-hydrolix",
        "mcp-hydrolix"
      ],
      "env": {
        "HYDROLIX_URL": "https://<your-hydrolix-hostname>",
        "HYDROLIX_USER": "<your-username>",
        "HYDROLIX_PASSWORD": "<your-password>"
      }
    }
  }
}

<your-hydrolix-hostname>, <your-username>, <your-password>을 실제 자격 증명으로 교체하세요.

[!NOTE] 옵션 B(pip)를 사용한 경우 "args" 필드 없이 "command": "mcp-hydrolix"을 사용하세요.

[!TIP] 파일에 이미 다른 항목이 있다면 전체 파일을 교체하지 말고 기존 "mcpServers" 객체 안에 "mcp-hydrolix" 블록을 추가하세요.

[!NOTE] 사용자 이름/비밀번호 대신 서비스 계정 토큰으로 인증하는 경우 인증을 참조하세요.

명령어를 찾을 수 없나요?

Claude Desktop은 셸의 PATH 없이 실행되므로 바이너리가 설치되어 있어도 찾지 못할 수 있습니다. 전체 경로를 찾아 구성의 "command" 값으로 사용하세요.

옵션 A (uv): uvx 찾기:

macOS / Linux: which uvx
Windows: where.exe uvx

옵션 B (pip): mcp-hydrolix 찾기:

macOS / Linux: which mcp-hydrolix
Windows: where.exe mcp-hydrolix

which/where.exe이 아무것도 반환하지 않으면 바이너리가 PATH에 없는 것입니다. 가장 깔끔한 해결책은 Python 환경과 PATH를 관리해 주는 옵션 A(uv)로 전환하는 것입니다.

4단계 — Claude Desktop 재시작

앱을 재시작하여 구성을 적용합니다.

macOS / Windows 사용자: 재시작하기 전에 Claude를 완전히 종료해야 합니다. macOS에서는 Cmd+Q를 누르거나 Dock 아이콘을 마우스 오른쪽 버튼으로 클릭하고 종료를 선택하세요. Windows에서는 시스템 트레이 아이콘을 사용하세요.

5단계 — 작동 확인

Claude Desktop에서 새 대화를 엽니다. 텍스트 입력 근처에 도구/망치 아이콘이 보이면 MCP 서버가 성공적으로 연결된 것입니다.
모든 것이 작동하는지 확인하려면 다음 프롬프트를 시도해 보세요:

Hydrolix MCP 도구를 사용하여 사용 가능한 데이터베이스를 나열해 주세요.

Claude가 list_databases 도구를 호출하고 클러스터의 데이터베이스 목록을 반환해야 합니다.

대신 Claude Code를 사용하시나요?

명령줄을 선호한다면 uv가 설치되어 있는지 확인하고(2단계의 옵션 A), 다음을 실행하세요:

claude mcp add --transport stdio hydrolix \
  --env HYDROLIX_URL=https://<your-hydrolix-hostname> \
  --env HYDROLIX_USER=<your-username> \
  --env HYDROLIX_PASSWORD=<your-password> \
  --env HYDROLIX_MCP_SERVER_TRANSPORT=stdio \
  -- uvx --python 3.13 --refresh-package mcp-hydrolix mcp-hydrolix

그런 다음 Claude Code를 열고 동일한 프롬프트로 테스트하세요:

Hydrolix MCP 도구를 사용하여 사용 가능한 데이터베이스를 나열해 주세요.

대신 VS Code를 사용하시나요?

원클릭 설치를 위해 이 README 상단의 VS Code에 설치 배지를 클릭하세요. UI 흐름을 선호한다면 명령 팔레트(Cmd+Shift+P / Ctrl+Shift+P)를 열고 MCP: 서버 추가를 실행한 다음 **명령(stdio)**을 선택하고 3단계의 uvx ... 명령과 env 블록을 재사용하세요.

도구

run_select_query
- Hydrolix 클러스터에서 SQL 쿼리를 실행합니다.
- 입력: sql (문자열): 실행할 SQL 쿼리입니다.
list_databases
- Hydrolix 클러스터의 모든 데이터베이스를 나열합니다.
list_tables
- 데이터베이스의 모든 테이블을 나열합니다.
- 입력: database (문자열): 데이터베이스 이름입니다.
get_table_info
- 스키마와 같은 테이블 메타데이터를 가져옵니다.
- 입력: database (문자열): 데이터베이스 이름입니다.
- 입력: table (문자열): 테이블 이름입니다.

효과적인 사용법

LLM 아키텍처가 매우 다양하기 때문에 모든 모델이 위 도구를 능동적으로 사용하는 것은 아니며, 모델에 제공되는 신중하게 구성된 도구 설명이 있더라도 안내 없이 효과적으로 사용하는 모델은 거의 없습니다. Hydrolix MCP 서버를 사용하면서 모델에서 최상의 결과를 얻으려면 다음을 권장합니다:

프롬프트에서 Hydrolix 데이터베이스 이름을 언급하고 도구 사용을 요청하세요 (예: "MCP 도구를 사용하여 내 Hydrolix 데이터베이스에 접근하여 ...해 주세요")
- 이렇게 하면 모델이 사용 가능한 MCP 도구를 사용하도록 장려하고 환각을 최소화합니다.
프롬프트에 시간 범위를 포함하고 (예: "2023년 12월 5일부터 2024년 1월 18일 사이에 ...") 출력을 타임스탬프 기준으로 정렬하도록 구체적으로 요청하세요.
- 이렇게 하면 모델이 기본 키 최적화를 활용하는 더 효율적인 쿼리를 작성하도록 유도합니다.

상태 확인 엔드포인트

HTTP 또는 SSE 전송으로 실행할 때 /health에서 상태 확인 엔드포인트를 사용할 수 있습니다. 이 엔드포인트는:

서버가 정상이고 Hydrolix에 연결할 수 있으면 Hydrolix 쿼리 헤드의 Clickhouse 버전과 함께 200 OK을 반환합니다.
서버가 Hydrolix 쿼리 헤드에 연결할 수 없으면 503 Service Unavailable을 반환합니다.

예시:

curl http://localhost:8000/health
# Response: OK - Connected to Hydrolix compatible with ClickHouse 24.3.1

구성

Hydrolix MCP 서버는 표준 MCP 서버 항목을 사용하여 구성됩니다. MCP 서버를 찾거나 선언하는 위치에 대한 구체적인 지침은 클라이언트 설명서를 참조하세요. Claude Desktop을 사용한 예제 설정이 아래에 문서화되어 있습니다.

Hydrolix MCP 서버를 시작하는 권장 방법은 uv 프로젝트 관리자를 통하는 것이며, 이는 격리된 환경에서 다른 모든 종속성 설치를 관리합니다.

인증

서버는 다음 우선 순위(높음에서 낮음)로 여러 인증 방법을 지원합니다:

요청별 Bearer 토큰: Authorization: Bearer <token> 헤더를 통해 제공되는 서비스 계정 토큰
요청별 GET 매개변수: ?token=<token> 쿼리 매개변수를 통해 제공되는 서비스 계정 토큰
환경 기반 자격 증명: 환경 변수를 통해 구성된 자격 증명
- 서비스 계정 토큰(HYDROLIX_TOKEN), 또는
- 사용자 이름과 비밀번호(HYDROLIX_USER 및 HYDROLIX_PASSWORD)

여러 인증 방법이 구성된 경우 서버는 위 우선 순위에 따라 사용 가능한 첫 번째 방법을 사용합니다. 요청별 인증은 HTTP 또는 SSE 전송 모드를 사용할 때만 사용할 수 있습니다.

참고: 읽기 전용 역할의 서비스 계정 토큰을 사용하는 것이 좋습니다.

사용자 이름과 비밀번호를 사용한 MCP 서버 정의 (JSON):

{
  "command": "uvx",
  "args": [
    "--python",
    "3.13",
    "--refresh-package",
    "mcp-hydrolix",
    "mcp-hydrolix"
  ],
  "env": {
    "HYDROLIX_URL": "https://<hydrolix-host>",
    "HYDROLIX_USER": "<hydrolix-user>",
    "HYDROLIX_PASSWORD": "<hydrolix-password>"
  }
}

서비스 계정 토큰을 사용한 MCP 서버 정의 (JSON):

{
  "command": "uvx",
  "args": [
    "--python",
    "3.13",
    "--refresh-package",
    "mcp-hydrolix",
    "mcp-hydrolix"
  ],
  "env": {
    "HYDROLIX_URL": "https://<hydrolix-host>",
    "HYDROLIX_TOKEN": "<hydrolix-service-account-token>"
  }
}

사용자 이름과 비밀번호를 사용한 MCP 서버 정의 (YAML):

command: uvx
args:
- --python
- "3.13"
- --refresh-package
- mcp-hydrolix
- mcp-hydrolix
env:
  HYDROLIX_URL: https://<hydrolix-host>
  HYDROLIX_USER: <hydrolix-user>
  HYDROLIX_PASSWORD: <hydrolix-password>

서비스 계정 토큰을 사용한 MCP 서버 정의 (YAML):

command: uvx
args:
- --python
- "3.13"
- --refresh-package
- mcp-hydrolix
- mcp-hydrolix
env:
  HYDROLIX_URL: https://<hydrolix-host>
  HYDROLIX_TOKEN: <hydrolix-service-account-token>

구성 예제 (Claude Desktop)

다음 위치에 있는 Claude Desktop 구성 파일을 엽니다:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%/Claude/claude_desktop_config.json
사용자 이름과 비밀번호를 사용하려면 mcpServers 구성 블록에 mcp-hydrolix 서버 항목을 추가합니다:

{
  "mcpServers": {
    "mcp-hydrolix": {
      "command": "uvx",
      "args": [
        "--python",
        "3.13",
        "--refresh-package",
        "mcp-hydrolix",
        "mcp-hydrolix"
      ],
      "env": {
        "HYDROLIX_URL": "https://<hydrolix-host>",
        "HYDROLIX_USER": "<hydrolix-user>",
        "HYDROLIX_PASSWORD": "<hydrolix-password>"
      }
    }
  }
}

서비스 계정을 활용하려면 다음 구성 블록을 사용합니다:

{
  "mcpServers": {
    "mcp-hydrolix": {
      "command": "uvx",
      "args": [
        "--python",
        "3.13",
        "--refresh-package",
        "mcp-hydrolix",
        "mcp-hydrolix"
      ],
      "env": {
        "HYDROLIX_URL": "https://<hydrolix-host>",
        "HYDROLIX_TOKEN": "<hydrolix-service-account-token>"
      }
    }
  }
}

환경 변수 정의를 Hydrolix 클러스터를 가리키도록 업데이트합니다.
(권장) uvx의 명령 항목을 찾아 uvx 실행 파일의 절대 경로로 교체합니다. 이렇게 하면 서버를 시작할 때 올바른 버전의 uvx이 사용됩니다. which uvx 또는 where.exe uvx을 사용하여 이 경로를 찾을 수 있습니다.
변경 사항을 적용하려면 Claude Desktop을 재시작합니다. Windows를 사용하는 경우 시스템 트레이 아이콘을 사용하여 클라이언트를 닫아 Claude가 완전히 중지되었는지 확인하세요.

구성 예제 (Claude Code)

Claude Code용 Hydrolix MCP 서버를 구성하려면 다음 명령을 실행하세요:

claude mcp add --transport stdio hydrolix \
  --env HYDROLIX_USER=<hydrolix-user> \
  --env HYDROLIX_PASSWORD=<hydrolix-password> \
  --env HYDROLIX_URL=https://<hydrolix-host> \
  --env HYDROLIX_MCP_SERVER_TRANSPORT=stdio \
  -- uvx --python 3.13 --refresh-package mcp-hydrolix mcp-hydrolix

환경 변수

다음 변수는 Hydrolix 연결을 구성하는 데 사용됩니다. 이러한 변수는 MCP 구성 블록(위에 표시된 대로), .env 파일 또는 기존 환경 변수를 통해 제공될 수 있습니다.

필수 변수

클러스터를 식별하려면 다음 중 하나를 반드시 설정해야 합니다:

HYDROLIX_URL (권장): Hydrolix 클러스터의 표준 공개 URL(예: https://mycluster.hydrolix.live). 일반적인 클러스터 외부 배포의 경우 이 단일 변수로 충분합니다 — HTTP 쿼리 엔드포인트와 REST /version 프로브 모두에 대한 호스트, 포트(스키마 기본값 443/80) 및 TLS 설정을 제공합니다.
HYDROLIX_HOST (지원 중단됨): Hydrolix 서버의 호스트 이름입니다. 이전 버전과의 호환성을 위해 여전히 허용되지만 HYDROLIX_URL로 교체해야 합니다.

HYDROLIX_MCP_SERVER_TRANSPORT이 http 또는 sse인 경우 HYDROLIX_URL이 특히 필요합니다(OAuth 메타데이터 엔드포인트가 이를 알립니다). 이러한 전송에는 HYDROLIX_HOST만으로는 충분하지 않습니다.

엔드포인트 재정의

이는 HYDROLIX_URL에서 파생된 값을 재정의합니다. HTTP 쿼리 엔드포인트와 버전 API가 다른 내부 호스트 이름이나 포트에 있는 클러스터 내 배포에 유용합니다. 재정의 우선 순위: 명시적 새 변수 > 지원 중단된 별칭 > HYDROLIX_URL 파생 > 하드 기본값.

HYDROLIX_HTTP_QUERY_HOST / HYDROLIX_HTTP_QUERY_PORT / HYDROLIX_HTTP_QUERY_SECURE: ClickHouse HTTP 쿼리 엔드포인트를 재정의합니다.
HYDROLIX_VERSION_API_HOST / HYDROLIX_VERSION_API_PORT / HYDROLIX_VERSION_API_SECURE: REST /version 프로브 엔드포인트를 재정의합니다. HYDROLIX_VERSION_API_SECURE은 기본적으로 확인된 HTTP 쿼리 보안 값에서 상속됩니다.

지원 중단된 변수

다음은 전환 기간 동안 여전히 허용되지만 향후 릴리스에서 제거될 예정입니다. 편의에 따라 마이그레이션하세요:

지원 중단됨	대체 항목
`HYDROLIX_HOST`	`HYDROLIX_URL` (선호) 또는 `HYDROLIX_HTTP_QUERY_HOST`
`HYDROLIX_PORT`	`HYDROLIX_HTTP_QUERY_PORT`
`HYDROLIX_SECURE`	`HYDROLIX_HTTP_QUERY_SECURE`
`HYDROLIX_API_HOST`	`HYDROLIX_VERSION_API_HOST`
`HYDROLIX_API_PORT`	`HYDROLIX_VERSION_API_PORT`

이러한 변수를 사용하는 외부 운영자는 HYDROLIX_URL로의 마이그레이션을 권고하는 일회성 시작 경고를 보게 됩니다. 클러스터 내(o6r 관리) 배포에서는 이 경고가 표시되지 않으며, 마이그레이션은 플랫폼에서 처리됩니다.

인증 변수

stdio 전송을 사용할 때는 하나 이상의 인증 방법을 구성해야 합니다:

HYDROLIX_TOKEN: 환경 기반 인증을 위한 서비스 계정 토큰
HYDROLIX_USER 및 HYDROLIX_PASSWORD: 환경 기반 인증을 위한 사용자 이름과 비밀번호 (둘 다 함께 제공되어야 함)

요약하면:

stdio의 경우 HYDROLIX_TOKEN 또는 HYDROLIX_USER+HYDROLIX_PASS(환경 자격 증명)를 반드시 사용해야 합니다.
http/sse의 경우 HYDROLIX_TOKEN 또는 HYDROLIX_USER+HYDROLIX_PASS(환경 자격 증명)를 사용할 수 있지만, 대신 요청별 자격 증명을 사용할 수도 있습니다.

환경이나 요청을 통해 자격 증명이 제공되지 않으면 요청이 실패합니다.

선택적 변수

HYDROLIX_VERIFY: SSL 인증서 검증 활성화/비활성화
- 기본값: "true"
- 인증서 검증을 비활성화하려면 "false"로 설정하세요 (프로덕션 환경에서는 권장하지 않음)
HYDROLIX_DATABASE: 사용할 기본 데이터베이스
- 기본값: 없음 (서버 기본값 사용)
- 특정 데이터베이스에 자동으로 연결하려면 설정하세요
HYDROLIX_MCP_SERVER_TRANSPORT: MCP 서버의 전송 방식을 설정합니다.
- 기본값: "stdio"
- 유효한 옵션: "stdio", "http", "sse". MCP Inspector와 같은 도구를 사용한 로컬 개발에 유용합니다.
HYDROLIX_MCP_BIND_HOST: HTTP 또는 SSE 전송 사용 시 MCP 서버가 바인딩할 호스트
- 기본값: "127.0.0.1"
- 모든 네트워크 인터페이스에 바인딩하려면 "0.0.0.0"로 설정하세요 (Docker 또는 원격 접속에 유용)
- 전송 방식이 "http" 또는 "sse"일 때만 사용됩니다
HYDROLIX_MCP_BIND_PORT: HTTP 또는 SSE 전송 사용 시 MCP 서버가 바인딩할 포트
- 기본값: "8000"
- 전송 방식이 "http" 또는 "sse"일 때만 사용됩니다
HYDROLIX_MAX_RAW_TIMERANGE: 비요약 테이블에 대한 쿼리에 허용되는 최대 시간 범위(초)
- 기본값: 21600 (6시간)
- 요약 테이블을 대상으로 하는 쿼리는 이 제한의 영향을 받지 않습니다

MCP Inspector 또는 HTTP 전송을 통한 원격 접속의 경우:

HYDROLIX_URL=https://my-cluster.hydrolix.net
HYDROLIX_USER=default
HYDROLIX_PASSWORD=myPassword
HYDROLIX_MCP_SERVER_TRANSPORT=http
HYDROLIX_MCP_BIND_HOST=0.0.0.0  # Bind to all interfaces
HYDROLIX_MCP_BIND_PORT=4200  # Custom port (default: 8000)

HTTP 전송 사용 시, 서버는 구성된 포트(기본값 8000)에서 실행됩니다. 예를 들어, 위 구성의 경우:

MCP 엔드포인트: http://localhost:4200/mcp
상태 확인: http://localhost:4200/health

HTTP 전송에서 요청별 인증 사용하기

HTTP 또는 SSE 전송 사용 시, 환경 기반 자격 증명을 생략하고 대신 요청별로 인증을 제공할 수 있습니다. 이는 다중 사용자 시나리오나 MCP 서버를 로컬에서 실행하는 것을 지원하지 않는 클라이언트에 유용합니다.

요청별 인증을 사용하여 원격 HTTP 서버에 연결하는 mcpServers 구성 예시:

{
  "mcpServers": {
    "mcp-hydrolix-remote": {
      "url": "https://my-hydrolix-mcp.example.com/mcp?token=<service-account-token>"
    }
  }
}

환경 자격 증명 없이 자체 HTTP 서버를 실행하기 위한 최소 .env 구성 예시:

HYDROLIX_URL=https://my-cluster.hydrolix.net
HYDROLIX_MCP_SERVER_TRANSPORT=http

MCP 사양의 일부는 아니지만, 많은 MCP 클라이언트에서 MCP 발행 요청에 헤더를 추가할 수 있습니다. 이것이 가능한 경우, 보안 강화를 위해 쿼리 매개변수 대신 Authorization: Bearer <sa-token-here> 헤더를 통해 서비스 계정 토큰을 전달하도록 MCP 클라이언트를 구성하는 것을 권장합니다.

참고: 바인드 호스트 및 포트 설정은 전송 방식이 "http" 또는 "sse"로 설정된 경우에만 사용됩니다.

엔드투엔드 테스트

tests/e2e/ 아래의 별도 스위트는 로컬 작업 트리를 라이브 Hydrolix Kubernetes 클러스터에 배포하고 실행 중인 파드에 대해 MCP 도구의 스모크 테스트를 수행합니다. 이는 기본 테스트 실행 및 사전 푸시 훅에서 제외되며, 실행하려면 end_to_end pytest 마커와 자격 증명을 통한 명시적 옵트인이 필요합니다. 실행 지침은 tests/e2e/README.md을 참조하세요.