
Mcp Hydrolix
io.github.hydrolix由 GitHub 帳號 hydrolix 發布v0.3.9更新於 Nov 17, 2026
An MCP server to query Hydrolix
概覽
一個本機 MCP 伺服器,讓助理在 Hydrolix 叢集上執行 SQL 查詢並瀏覽資料庫、資料表與結構描述。
- 可以做什麼
- 在 Hydrolix 叢集上執行 SQL SELECT 查詢,可限制結果儲存格預算,並須填寫查詢用途(會記錄為查詢註解)
- 列出叢集上的所有資料庫
- 列出指定資料庫中的所有資料表
- 讀取指定資料庫與資料表的詮釋資料(例如結構描述)
- 適用情境
- 適合想用自然語言探索或查詢 Hydrolix 叢集的情境,例如列出資料庫、檢視資料表結構,或執行帶時間範圍的 SQL 分析而不必手寫查詢。
- 執行需求
- 以 stdio 方式在本機執行,通常用 uvx 啟動(由 uv 管理 Python),或以 pip 安裝並需要 Python 3.13+。需要能連線到叢集網路,並設定 HYDROLIX_URL,以及 HYDROLIX_TOKEN 或同時設定 HYDROLIX_USER 與 HYDROLIX_PASSWORD。
安裝
在 SourceWeft 中
- 開啟 儀表板中的 Mcp Hydrolix,將其新增到工作區。
- 為需要使用其工具的對話啟用該服務。
Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。
其他 MCP 客戶端
參照 儲存庫 中的啟動說明。
README
Hydrolix MCP Server
[PyPI - Version] [Install in VS Code] [Install in VS Code Insiders]
An MCP server for Hydrolix.
Quickstart
Get up and running in a few minutes. This section covers Claude Desktop and Claude Code.
Step 1 — Prerequisites
Before you begin, make sure you have:
- Hydrolix credentials — your cluster hostname plus either a username/password or a service account token. If you don't have these, ask your Hydrolix administrator.
- Claude Desktop — download from claude.ai/download.
Step 2 — Install the MCP server
Choose the method that matches your setup:
Option A: Using uv (recommended)
uv manages Python automatically and downloads mcp-hydrolix on demand, so no separate install step is needed. If you don't have uv, install it:
macOS / Linux:
Windows (PowerShell):
Option B: Using pip
Requires Python 3.13+. If you need to install Python, download it from python.org.
Step 3 — Configure Claude Desktop
-
Open the Claude Desktop configuration file:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
- macOS:
-
Add the following entry to the
"mcpServers"object (create the file with this content if it doesn't exist yet):
Replace <your-hydrolix-hostname>, <your-username>, and <your-password> with your actual credentials.
[!NOTE] If you used Option B (pip), use
"command": "mcp-hydrolix"with no"args"field instead.
[!TIP] If the file already has other entries, add the
"mcp-hydrolix"block inside the existing"mcpServers"object rather than replacing the whole file.
[!NOTE] If you authenticate with a service account token instead of username/password, see Authentication.
Command not found?
Claude Desktop launches without your shell's PATH, so it may not locate the binary even if it is installed. Find the full path and use it as the "command" value in the config.
Option A (uv): find uvx:
- macOS / Linux:
which uvx - Windows:
where.exe uvx
Option B (pip): find mcp-hydrolix:
- macOS / Linux:
which mcp-hydrolix - Windows:
where.exe mcp-hydrolix
If which/where.exe returns nothing, the binary isn't on your PATH. The cleanest fix is to switch to Option A (uv), which manages the Python environment and PATH for you.
Step 4 — Restart Claude Desktop
Restart the app to apply the configuration.
macOS / Windows users: Make sure to fully quit Claude before restarting. On macOS, press Cmd+Q or right-click the Dock icon and choose Quit. On Windows, use the system tray icon.
Step 5 — Verify it's working
-
Open a new conversation in Claude Desktop. Look for a tools/hammer icon near the text input — this confirms the MCP server connected successfully.
-
Try this prompt to confirm everything is working:
Using your Hydrolix MCP tools, list the available databases.
Claude should call the list_databases tool and return a list of databases from your cluster.
Using Claude Code instead?
If you prefer the command line, make sure uv is installed (Option A from Step 2), then run:
Then open Claude Code and test with the same prompt:
Using your Hydrolix MCP tools, list the available databases.
Using VS Code instead?
Click the Install in VS Code badge at the top of this README for a one-click install. If you prefer the UI flow, open the Command Palette (Cmd+Shift+P / Ctrl+Shift+P), run MCP: Add Server, choose Command (stdio), and reuse the uvx ... command and env block from Step 3.
Tools
-
run_select_query- Execute SQL queries on your Hydrolix cluster.
- Input:
query(string): The SQL query to execute. - Input:
max_cells(integer, optional): Result cell budget (rows × columns); when the server sets a cap, a caller can only lower it. - Input:
purpose(string, required): Why the query is being run; recorded with the query ashdx_query_comment. - A trailing
FORMATclause is removed; the server selects the wire format.
-
list_databases- List all databases on your Hydrolix cluster.
-
list_tables- List all tables in a database.
- Input:
database(string): The name of the database.
-
get_table_info- Get table metadata such as schema
- Input:
database(string): The name of the database. - Input:
table(string): The name of the table.
Effective Usage
Due to the wide variety in LLM architectures, not all models will proactively use the tools above, and few will use them effectively without guidance, even with the carefully-constructed tool descriptions provided to the model. To get the best results out of your model while using the Hydrolix MCP server, we recommend the following:
- Refer to your Hydrolix database by name and request tool usage in your prompts (e.g., "Using MCP tools to access my Hydrolix database, please ...")
- This encourages the model to use the MCP tools available and minimizes hallucinations.
- Include time ranges in your prompts (e.g., "Between December 5 2023 and January 18 2024, ...") and specifically request that the output be ordered by timestamp.
- This prompts the model to write more efficient queries that take advantage of primary key optimizations
Health Check Endpoint
When running with HTTP or SSE transport, a health check endpoint is available at /health. This endpoint:
- Returns
200 OKwith the Hydrolix query-head's Clickhouse version if the server is healthy and can connect to Hydrolix - Returns
503 Service Unavailableif the server cannot connect to the Hydrolix query-head
Example:
Configuration
The Hydrolix MCP server is configured using a standard MCP server entry. Consult your client's documentation for specific instructions on where to find or declare MCP servers. An example setup using Claude Desktop is documented below.
The recommended way to launch the Hydrolix MCP server is via the uv project manager, which will manage installing all other dependencies in an isolated environment.
Authentication
The server supports multiple authentication methods with the following precedence (highest to lowest):
- Per-request Bearer token: Service account token provided via
Authorization: Bearer <token>header - Per-request GET parameter: Service account token provided via
?token=<token>query parameter - Environment-based credentials: Credentials configured via environment variables
- Service account token (
HYDROLIX_TOKEN), or - Username and password (
HYDROLIX_USERandHYDROLIX_PASSWORD)
- Service account token (
When multiple authentication methods are configured, the server will use the first available method in the precedence order above. Per-request authentication is only available when using HTTP or SSE transport modes. The ?token= form exists for clients that cannot send headers; set HYDROLIX_ALLOW_TOKEN_QUERY_PARAM=false on deployments where every client sends the Authorization header (see Per-request credentials).
Note: Using a service account token with a readonly role is recommended.
MCP Server definition using username and password (JSON):
MCP Server definition using service account token (JSON):
MCP Server definition using username and password (YAML):
MCP Server definition using service account token (YAML):
Configuration Example (Claude Desktop)
-
Open the Claude Desktop configuration file located at:
- On macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - On Windows:
%APPDATA%/Claude/claude_desktop_config.json
- On macOS:
-
Add a
mcp-hydrolixserver entry to themcpServersconfig block to use username and password:
To leverage service account use the following config block:
-
Update the environment variable definitions to point to your Hydrolix cluster.
-
(Recommended) Locate the command entry for
uvxand replace it with the absolute path to theuvxexecutable. This ensures that the correct version ofuvxis used when starting the server. You can find this path usingwhich uvxorwhere.exe uvx. -
Restart Claude Desktop to apply the changes. If you are using Windows, ensure Claude is stopped completely by closing the client using the system tray icon.
Configuration Example (Claude Code)
To configure the Hydrolix MCP server for Claude Code, run the following command:
Environment Variables
The following variables are used to configure the Hydrolix connection. These variables may be provided via the MCP config block (as shown above), a .env file, or traditional environment variables.
Required Variables
You MUST set one of the following to identify the cluster:
HYDROLIX_URL(recommended): The canonical public URL of your Hydrolix cluster, e.g.https://mycluster.hydrolix.live. For typical out-of-cluster deployments this single variable is sufficient — it supplies the host, port (scheme-default 443/80), and TLS settings for both the HTTP query endpoint and the REST/versionprobe.HYDROLIX_HOST(deprecated): The hostname of your Hydrolix server. Still honored for backwards compatibility but should be replaced byHYDROLIX_URL.
When HYDROLIX_MCP_SERVER_TRANSPORT is http or sse, HYDROLIX_URL specifically is required (a forthcoming OAuth metadata endpoint would advertise it). HYDROLIX_HOST alone is not sufficient for these transports.
Authentication Variables
At least one authentication method must be configured when using the stdio transport:
HYDROLIX_TOKEN: Service account token for environment-based authenticationHYDROLIX_USERandHYDROLIX_PASSWORD: Username and password for environment-based authentication (both must be provided together)
In summary:
- For stdio, you MUST use HYDROLIX_TOKEN or HYDROLIX_USER+HYDROLIX_PASS (environmental credentials)
- For http/sse, you MAY use HYDROLIX_TOKEN or HYDROLIX_USER+HYDROLIX_PASS (environmental credentials), but you may instead use per-request credentials.
If no credentials are provided via the environment or the request, the request will fail.
Using Per-Request Authentication with HTTP Transport
When using HTTP or SSE transport, you can omit environment-based credentials and instead provide authentication per-request. This is useful for multi-user scenarios or with clients that don't support running MCP servers locally.
Example mcpServers configuration connecting to a remote HTTP server with per-request authentication:
Example minimal .env configuration for running your own HTTP server without environment credentials:
Though not part of the MCP specification, many MCP clients allow adding headers to MCP-issued requests. When this is possible, we recommend configuring the MCP client to pass a service account token via the Authorization: Bearer <sa-token-here> header instead of as a query parameter for greater security.
Note: The bind host and port settings are only used when transport is set to "http" or "sse".
Optional Variables
See docs/CONFIG.md for endpoint overrides, deprecated variable aliases, and the full set of optional tuning variables (timeouts, query SETTINGS overrides, result truncation, HTTP/SSE worker tuning, proxy, metrics, and escape hatches).
Maintainers
Tasks that need operational privileges — running the end-to-end suite against a
live Hydrolix cluster, and cutting a release — are documented separately in
MAINTAINERS.md.
來源:README.md,提交 bb179ac
工具
0版本歷史
3- v0.3.9最新Nov 17, 2026
- v0.3.8Nov 14, 2026
- v0.2.3Sep 16, 2026
評分
已滿足適用檢查項的 50%
該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。
- 近 30 天內可連通25 分
請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。
- 已宣告認證方式10 分
請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。
- 已列出工具15 分
請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。
- 描述必需15 分
- 圖示10 分
- 文件15 分
- 授權條款10 分