Hydrolix

공식

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

GitHub

이 MCP 사용해 보기스폰서

Hydrolix MCP(으)로 무엇을 할 수 있나요?

SQL 쿼리 실행 — 어시스턴트에게 Hydrolix 클러스터에서 run_select_query를 실행하도록 요청하고, 선택적으로 셀 제한 및 목적 주석을 포함할 수 있습니다.
데이터베이스 나열 — 어시스턴트가 list_databases를 호출하여 Hydrolix 클러스터에서 사용 가능한 모든 데이터베이스를 열거하도록 하세요.
테이블 스키마 탐색 — list_tables 및 get_table_info를 사용하여 테이블을 발견하고 모든 데이터베이스의 스키마와 같은 메타데이터를 검색하세요.
시간 범위로 쿼리 — 특정 날짜 범위 내에서 타임스탬프 순서의 결과를 요청하여 기본 키 최적화를 활용해 효율적인 쿼리를 수행하세요.

문서

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 쿼리를 실행합니다.
- 입력: query (문자열): 실행할 SQL 쿼리.
- 입력: max_cells (정수, 선택 사항): 결과 셀 예산(행 × 열); 서버가 상한을 설정하면 호출자는 낮출 수만 있습니다.
- 입력: purpose (문자열, 필수): 쿼리가 실행되는 이유; 쿼리와 함께 hdx_query_comment로 기록됩니다.
- 끝의 FORMAT 절은 제거됩니다; 서버가 와이어 형식을 선택합니다.
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 전송 모드를 사용할 때만 사용할 수 있습니다. ?token= 형식은 헤더를 보낼 수 없는 클라이언트를 위한 것입니다. 모든 클라이언트가 Authorization 헤더를 보내는 배포에서는 HYDROLIX_ALLOW_TOKEN_QUERY_PARAM=false을 설정하세요 (요청별 자격 증명 참조).

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

사용자 이름과 비밀번호를 사용한 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만으로는 이러한 전송에 충분하지 않습니다.

인증 변수

stdio 전송을 사용할 때는 최소한 하나의 인증 방법이 구성되어야 합니다:

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

요약:

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

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

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"로 설정된 경우에만 사용됩니다.

선택적 변수

엔드포인트 재정의, 더 이상 사용되지 않는 변수 별칭 및 전체 선택적 튜닝 변수(시간 초과, 쿼리 SETTINGS 재정의, 결과 잘림, HTTP/SSE 작업자 튜닝, 프록시, 메트릭 및 이스케이프 해치)는 **docs/CONFIG.md**를 참조하세요.

관리자

운영 권한이 필요한 작업 — 라이브 Hydrolix 클러스터에 대해 종단 간 스위트를 실행하고 릴리스를 만드는 작업 — 은 MAINTAINERS.md에 별도로 문서화되어 있습니다.