Hydrolix

官方

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

GitHub

試用此 MCP贊助

你可以用 Hydrolix MCP 做什麼？

執行 SQL 查詢 — 要求您的助理針對您的 Hydrolix 叢集執行 run_select_query，可選擇設定儲存格上限與用途註解。
列出資料庫 — 讓您的助理呼叫 list_databases 來列舉 Hydrolix 叢集上所有可用的資料庫。
探索資料表結構 — 使用 list_tables 與 get_table_info 來探索資料表，並為任何資料庫擷取如結構描述等中繼資料。
使用時間範圍查詢 — 在特定日期範圍內請求依時間戳記排序的結果，以利用主鍵最佳化來提升查詢效率。

文件

Hydrolix MCP Server

一個用於 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] 如果您使用服務帳戶權杖而非使用者名稱/密碼進行驗證，請參閱 Authentication。

找不到命令？

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 頂部的 Install in VS Code 徽章即可一鍵安裝。如果您偏好 UI 流程，請開啟命令面板（Cmd+Shift+P / Ctrl+Shift+P），執行 MCP: Add Server，選擇 Command (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，會回傳 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 的範例設定。

建議透過 uv 專案管理員啟動 Hydrolix MCP 伺服器，它會在隔離環境中管理所有其他相依性的安裝。

驗證

伺服器支援多種驗證方法，優先順序如下（從高到低）：

每個請求的 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 叢集。

4.（建議）找到 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」時使用。

選用變數

請參閱 docs/CONFIG.md 以了解端點覆寫、已棄用的變數別名，以及完整的選用調整變數集（逾時、查詢 SETTINGS 覆寫、結果截斷、HTTP/SSE 工作者調整、代理、指標和逃生門）。

維護者

需要操作權限的工作——針對實際 Hydrolix 叢集執行端對端測試套件，以及發佈版本——已分別記錄於 MAINTAINERS.md。