Hydrolix MCP Server | Awesome MCP Servers

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: 新增伺服器，選擇 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 對於這些傳輸方式是不夠的。

端點覆寫

這些會覆寫從 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 發出的請求中。在可行的情況下，我們建議設定 MCP 客戶端透過 Authorization: Bearer <sa-token-here> 標頭傳遞服務帳戶權杖，而不是作為查詢參數，以獲得更高的安全性。

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

端對端測試

位於 tests/e2e/ 下的獨立測試套件會將本機工作樹部署到即時的 Hydrolix Kubernetes 叢集，並對執行中的 Pod 進行 MCP 工具的煙霧測試。它被排除在預設測試執行和預推送掛鉤之外；執行它需要透過 end_to_end pytest 標記明確選擇加入，並提供憑證。請參閱 tests/e2e/README.md 以取得操作手冊。