Hydrolix

chính thức

Tích hợp datalake chuỗi thời gian Hydrolix cung cấp khả năng khám phá lược đồ và truy vấn cho các quy trình làm việc dựa trên LLM.

GitHub

Bạn có thể làm gì với Hydrolix MCP?

Liệt kê cơ sở dữ liệu có sẵn — Yêu cầu trợ lý liệt kê tất cả cơ sở dữ liệu trong cụm Hydrolix của bạn bằng list_databases.
Khám phá bảng trong cơ sở dữ liệu — Yêu cầu danh sách tất cả bảng trong một cơ sở dữ liệu cụ thể qua list_tables.
Kiểm tra lược đồ bảng — Truy xuất tên cột, kiểu dữ liệu và siêu dữ liệu cho một bảng nhất định bằng get_table_info.
Chạy truy vấn SQL — Thực thi SQL tùy ý trên cụm Hydrolix của bạn bằng run_select_query để phân tích dữ liệu nhật ký hoặc sự kiện.

Tài liệu

Hydrolix MCP Server

Một máy chủ MCP dành cho Hydrolix.

Bắt đầu nhanh

Thiết lập và chạy trong vài phút. Phần này bao gồm Claude Desktop và Claude Code.

Bước 1 — Điều kiện tiên quyết

Trước khi bắt đầu, hãy đảm bảo bạn có:

Thông tin xác thực Hydrolix — tên máy chủ cụm của bạn cùng với tên người dùng/mật khẩu hoặc mã thông báo tài khoản dịch vụ. Nếu chưa có, hãy liên hệ quản trị viên Hydrolix của bạn.
Claude Desktop — tải xuống từ claude.ai/download.

Bước 2 — Cài đặt máy chủ MCP

Chọn phương pháp phù hợp với thiết lập của bạn:

Tùy chọn A: Sử dụng uv (khuyến nghị)

uv tự động quản lý Python và tải xuống mcp-hydrolix theo yêu cầu, do đó không cần bước cài đặt riêng. Nếu chưa có uv, hãy cài đặt nó:

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"

Tùy chọn B: Sử dụng pip

Yêu cầu Python 3.13+. Nếu cần cài đặt Python, hãy tải xuống từ python.org.

pip install mcp-hydrolix

Bước 3 — Cấu hình Claude Desktop

Mở tệp cấu hình 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
Thêm mục sau vào đối tượng "mcpServers" (tạo tệp với nội dung này nếu chưa tồn tại):

{
  "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>"
      }
    }
  }
}

Thay thế <your-hydrolix-hostname>, <your-username> và <your-password> bằng thông tin xác thực thực tế của bạn.

[!LƯU Ý] Nếu bạn đã sử dụng Tùy chọn B (pip), hãy sử dụng "command": "mcp-hydrolix" mà không có trường "args".

[!MẸO] Nếu tệp đã có các mục khác, hãy thêm khối "mcp-hydrolix" vào bên trong đối tượng "mcpServers" hiện có thay vì thay thế toàn bộ tệp.

[!LƯU Ý] Nếu bạn xác thực bằng mã thông báo tài khoản dịch vụ thay vì tên người dùng/mật khẩu, hãy xem Xác thực.

Không tìm thấy lệnh?

Claude Desktop khởi chạy mà không có PATH của shell, vì vậy nó có thể không định vị được tệp nhị phân ngay cả khi đã được cài đặt. Tìm đường dẫn đầy đủ và sử dụng nó làm giá trị "command" trong cấu hình.

Tùy chọn A (uv): tìm uvx:

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

Tùy chọn B (pip): tìm mcp-hydrolix:

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

Nếu which/where.exe không trả về gì, tệp nhị phân không nằm trong PATH của bạn. Cách khắc phục đơn giản nhất là chuyển sang Tùy chọn A (uv), cách này quản lý môi trường Python và PATH cho bạn.

Bước 4 — Khởi động lại Claude Desktop

Khởi động lại ứng dụng để áp dụng cấu hình.

Người dùng macOS / Windows: Đảm bảo thoát hoàn toàn Claude trước khi khởi động lại. Trên macOS, nhấn Cmd+Q hoặc nhấp chuột phải vào biểu tượng Dock và chọn Thoát. Trên Windows, sử dụng biểu tượng khay hệ thống.

Bước 5 — Xác minh hoạt động

Mở một cuộc trò chuyện mới trong Claude Desktop. Tìm biểu tượng công cụ/búa gần khu vực nhập văn bản — điều này xác nhận máy chủ MCP đã kết nối thành công.
Thử lời nhắc này để xác nhận mọi thứ đang hoạt động:

Sử dụng các công cụ Hydrolix MCP của bạn, liệt kê các cơ sở dữ liệu khả dụng.

Claude sẽ gọi công cụ list_databases và trả về danh sách các cơ sở dữ liệu từ cụm của bạn.

Sử dụng Claude Code thay thế?

Nếu bạn thích dòng lệnh hơn, hãy đảm bảo uv đã được cài đặt (Tùy chọn A từ Bước 2), sau đó chạy:

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

Sau đó mở Claude Code và kiểm tra với cùng lời nhắc:

Sử dụng các công cụ Hydrolix MCP của bạn, liệt kê các cơ sở dữ liệu khả dụng.

Sử dụng VS Code thay thế?

Nhấp vào huy hiệu Cài đặt trong VS Code ở đầu README này để cài đặt chỉ với một cú nhấp chuột. Nếu bạn thích quy trình giao diện người dùng, hãy mở Bảng lệnh (Cmd+Shift+P / Ctrl+Shift+P), chạy MCP: Thêm máy chủ, chọn Lệnh (stdio) và sử dụng lại lệnh uvx ... và khối env từ Bước 3.

Công cụ

run_select_query
- Thực thi các truy vấn SQL trên cụm Hydrolix của bạn.
- Đầu vào: sql (chuỗi): Truy vấn SQL cần thực thi.
list_databases
- Liệt kê tất cả cơ sở dữ liệu trên cụm Hydrolix của bạn.
list_tables
- Liệt kê tất cả bảng trong một cơ sở dữ liệu.
- Đầu vào: database (chuỗi): Tên của cơ sở dữ liệu.
get_table_info
- Lấy siêu dữ liệu bảng như lược đồ
- Đầu vào: database (chuỗi): Tên của cơ sở dữ liệu.
- Đầu vào: table (chuỗi): Tên của bảng.

Sử dụng hiệu quả

Do sự đa dạng trong kiến trúc LLM, không phải tất cả các mô hình đều sẽ chủ động sử dụng các công cụ trên, và ít mô hình sẽ sử dụng chúng hiệu quả nếu không có hướng dẫn, ngay cả với các mô tả công cụ được xây dựng cẩn thận cung cấp cho mô hình. Để có kết quả tốt nhất từ mô hình của bạn khi sử dụng máy chủ Hydrolix MCP, chúng tôi khuyến nghị:

Tham chiếu đến cơ sở dữ liệu Hydrolix của bạn theo tên và yêu cầu sử dụng công cụ trong lời nhắc của bạn (ví dụ: "Sử dụng các công cụ MCP để truy cập cơ sở dữ liệu Hydrolix của tôi, vui lòng ...")
- Điều này khuyến khích mô hình sử dụng các công cụ MCP có sẵn và giảm thiểu ảo giác.
Bao gồm phạm vi thời gian trong lời nhắc của bạn (ví dụ: "Từ ngày 5 tháng 12 năm 2023 đến ngày 18 tháng 1 năm 2024, ...") và yêu cầu cụ thể rằng đầu ra được sắp xếp theo dấu thời gian.
- Điều này nhắc mô hình viết các truy vấn hiệu quả hơn, tận dụng tối ưu hóa khóa chính

Điểm cuối kiểm tra sức khỏe

Khi chạy với truyền tải HTTP hoặc SSE, một điểm cuối kiểm tra sức khỏe có sẵn tại /health. Điểm cuối này:

Trả về 200 OK với phiên bản Clickhouse của đầu truy vấn Hydrolix nếu máy chủ khỏe mạnh và có thể kết nối với Hydrolix
Trả về 503 Service Unavailable nếu máy chủ không thể kết nối với đầu truy vấn Hydrolix

Ví dụ:

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

Cấu hình

Máy chủ Hydrolix MCP được cấu hình bằng cách sử dụng một mục máy chủ MCP tiêu chuẩn. Tham khảo tài liệu của máy khách của bạn để biết hướng dẫn cụ thể về nơi tìm hoặc khai báo máy chủ MCP. Một thiết lập ví dụ sử dụng Claude Desktop được ghi lại bên dưới.

Cách khuyến nghị để khởi chạy máy chủ Hydrolix MCP là thông qua trình quản lý dự án uv, nó sẽ quản lý việc cài đặt tất cả các phụ thuộc khác trong một môi trường biệt lập.

Xác thực

Máy chủ hỗ trợ nhiều phương thức xác thực với thứ tự ưu tiên sau (từ cao nhất đến thấp nhất):

Mã thông báo Bearer theo yêu cầu: Mã thông báo tài khoản dịch vụ được cung cấp qua tiêu đề Authorization: Bearer <token>
Tham số GET theo yêu cầu: Mã thông báo tài khoản dịch vụ được cung cấp qua tham số truy vấn ?token=<token>
Thông tin xác thực dựa trên môi trường: Thông tin xác thực được cấu hình qua biến môi trường
- Mã thông báo tài khoản dịch vụ (HYDROLIX_TOKEN), hoặc
- Tên người dùng và mật khẩu (HYDROLIX_USER và HYDROLIX_PASSWORD)

Khi nhiều phương thức xác thực được cấu hình, máy chủ sẽ sử dụng phương thức khả dụng đầu tiên theo thứ tự ưu tiên ở trên. Xác thực theo yêu cầu chỉ khả dụng khi sử dụng các chế độ truyền tải HTTP hoặc SSE.

Lưu ý: Khuyến nghị sử dụng mã thông báo tài khoản dịch vụ với vai trò chỉ đọc.

Định nghĩa máy chủ MCP sử dụng tên người dùng và mật khẩu (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>"
  }
}

Định nghĩa máy chủ MCP sử dụng mã thông báo tài khoản dịch vụ (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>"
  }
}

Định nghĩa máy chủ MCP sử dụng tên người dùng và mật khẩu (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>

Định nghĩa máy chủ MCP sử dụng mã thông báo tài khoản dịch vụ (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>

Ví dụ cấu hình (Claude Desktop)

Mở tệp cấu hình Claude Desktop nằm tại:
- Trên macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Trên Windows: %APPDATA%/Claude/claude_desktop_config.json
Thêm một mục máy chủ mcp-hydrolix vào khối cấu hình mcpServers để sử dụng tên người dùng và mật khẩu:

{
  "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>"
      }
    }
  }
}

Để tận dụng tài khoản dịch vụ, hãy sử dụng khối cấu hình sau:

{
  "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>"
      }
    }
  }
}

Cập nhật các định nghĩa biến môi trường để trỏ đến cụm Hydrolix của bạn.
(Khuyến nghị) Xác định vị trí mục lệnh cho uvx và thay thế nó bằng đường dẫn tuyệt đối đến tệp thực thi uvx. Điều này đảm bảo rằng phiên bản chính xác của uvx được sử dụng khi khởi động máy chủ. Bạn có thể tìm đường dẫn này bằng cách sử dụng which uvx hoặc where.exe uvx.
Khởi động lại Claude Desktop để áp dụng các thay đổi. Nếu bạn đang sử dụng Windows, hãy đảm bảo Claude được dừng hoàn toàn bằng cách đóng máy khách bằng biểu tượng khay hệ thống.

Ví dụ cấu hình (Claude Code)

Để cấu hình máy chủ Hydrolix MCP cho Claude Code, hãy chạy lệnh sau:

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

Biến môi trường

Các biến sau được sử dụng để cấu hình kết nối Hydrolix. Các biến này có thể được cung cấp qua khối cấu hình MCP (như được hiển thị ở trên), tệp .env hoặc các biến môi trường truyền thống.

Biến bắt buộc

Bạn PHẢI đặt một trong những biến sau để xác định cụm:

HYDROLIX_URL (khuyến nghị): URL công khai chính tắc của cụm Hydrolix của bạn, ví dụ: https://mycluster.hydrolix.live. Đối với các triển khai ngoài cụm thông thường, biến duy nhất này là đủ — nó cung cấp máy chủ, cổng (mặc định lược đồ 443/80) và cài đặt TLS cho cả điểm cuối truy vấn HTTP và thăm dò REST /version.
HYDROLIX_HOST (không dùng nữa): Tên máy chủ của máy chủ Hydrolix của bạn. Vẫn được tôn trọng để tương thích ngược nhưng nên được thay thế bằng HYDROLIX_URL.

Khi HYDROLIX_MCP_SERVER_TRANSPORT là http hoặc sse, HYDROLIX_URL cụ thể là bắt buộc (một điểm cuối siêu dữ liệu OAuth sắp tới sẽ quảng cáo nó). Chỉ HYDROLIX_HOST là không đủ cho các truyền tải này.

Biến xác thực

Ít nhất một phương thức xác thực phải được cấu hình khi sử dụng truyền tải stdio:

HYDROLIX_TOKEN: Mã thông báo tài khoản dịch vụ để xác thực dựa trên môi trường
HYDROLIX_USER và HYDROLIX_PASSWORD: Tên người dùng và mật khẩu để xác thực dựa trên môi trường (cả hai phải được cung cấp cùng nhau)

Tóm lại:

Đối với stdio, bạn PHẢI sử dụng HYDROLIX_TOKEN hoặc HYDROLIX_USER+HYDROLIX_PASS (thông tin xác thực môi trường)
Đối với http/sse, bạn CÓ THỂ sử dụng HYDROLIX_TOKEN hoặc HYDROLIX_USER+HYDROLIX_PASS (thông tin xác thực môi trường), nhưng thay vào đó bạn có thể sử dụng thông tin xác thực theo yêu cầu.

Nếu không có thông tin xác thực nào được cung cấp qua môi trường hoặc yêu cầu, yêu cầu sẽ thất bại.

Sử dụng Xác thực theo yêu cầu với Truyền tải HTTP

Khi sử dụng truyền tải HTTP hoặc SSE, bạn có thể bỏ qua thông tin xác thực dựa trên môi trường và thay vào đó cung cấp xác thực cho mỗi yêu cầu. Điều này hữu ích cho các tình huống nhiều người dùng hoặc với các máy khách không hỗ trợ chạy máy chủ MCP cục bộ.

Ví dụ cấu hình mcpServers kết nối đến máy chủ HTTP từ xa với xác thực theo yêu cầu:

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

Ví dụ cấu hình .env tối thiểu để chạy máy chủ HTTP của riêng bạn mà không có thông tin xác thực môi trường:

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

Mặc dù không phải là một phần của đặc tả MCP, nhiều máy khách MCP cho phép thêm tiêu đề vào các yêu cầu do MCP phát hành. Khi điều này có thể, chúng tôi khuyên bạn nên cấu hình máy khách MCP để truyền mã thông báo tài khoản dịch vụ qua tiêu đề Authorization: Bearer <sa-token-here> thay vì dưới dạng tham số truy vấn để bảo mật cao hơn.

Lưu ý: Cài đặt máy chủ liên kết và cổng chỉ được sử dụng khi truyền tải được đặt thành "http" hoặc "sse".

Biến tùy chọn

Xem docs/CONFIG.md để biết các ghi đè điểm cuối, bí danh biến không dùng nữa và bộ đầy đủ các biến điều chỉnh tùy chọn (thời gian chờ, ghi đè CÀI ĐẶT truy vấn, cắt ngắn kết quả, điều chỉnh worker HTTP/SSE, proxy, số liệu và lối thoát).

Người bảo trì

Các tác vụ yêu cầu đặc quyền vận hành — chạy bộ kiểm thử end-to-end dựa trên một cụm Hydrolix trực tiếp và cắt bản phát hành — được ghi lại riêng trong MAINTAINERS.md.