Hydrolix

官方

Hydrolix 時間序列資料湖整合，提供 LLM 工作流程的綱要探索與查詢能力。

GitHub

你可以用 Hydrolix MCP 做什麼？

列出可用的資料庫 — 要求助手使用 list_databases 列舉您 Hydrolix 叢集中的所有資料庫。
探索資料庫中的資料表 — 透過 list_tables 請求特定資料庫中所有資料表的清單。
檢查資料表結構 — 使用 get_table_info 擷取指定資料表的欄位名稱、型別和中繼資料。
執行 SQL 查詢 — 使用 run_select_query 對您的 Hydrolix 叢集執行任意 SQL，以分析日誌或事件資料。

文件

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)，請改用 "command": "mcp-hydrolix"，且不包含 "args" 欄位。

[!TIP] 如果檔案中已有其他項目，請將 "mcp-hydrolix" 區塊新增至現有的 "mcpServers" 物件內，而不是取代整個檔案。

[!NOTE] 如果您使用服務帳戶權杖而非使用者名稱/密碼進行驗證，請參閱驗證。

找不到指令？

Claude Desktop 啟動時不會載入您 shell 的 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 中。最簡潔的解決方案是切換到選項 A (uv)，它會為您管理 Python 環境和 PATH。

步驟 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: Add Server，選擇 Command (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，則會回傳 200 OK 以及 Hydrolix 查詢頭的 Clickhouse 版本
如果伺服器無法連線到 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
將 mcp-hydrolix 伺服器項目新增至 mcpServers 設定區塊，以使用使用者名稱和密碼：

{
  "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 發出的請求中。當可以這樣做時，我們建議設定 MCP 客戶端透過 Authorization: Bearer <sa-token-here> 標頭傳遞服務帳戶權杖，而不是作為查詢參數，以提高安全性。

注意：繫結主機和連接埠設定僅在傳輸設定為 "http" 或 "sse" 時使用。

可選變數

關於端點覆寫、已棄用的變數別名以及完整的可選調整變數（逾時、查詢 SETTINGS 覆寫、結果截斷、HTTP/SSE 工作執行緒調整、代理、指標和逃生艙口），請參閱 docs/CONFIG.md。

維護者

需要操作權限的任務 — 針對即時 Hydrolix 叢集執行端對端測試套件，以及發佈版本 — 會單獨記錄在 MAINTAINERS.md 中。