Hydrolix MCP Server

<!-- mcp-name: io.github.hydrolix/mcp-hydrolix -->

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:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Option B: Using pip

Requires Python 3.13+. If you need to install Python, download it from python.org.

pip install mcp-hydrolix

Step 3 — Configure Claude Desktop

1. 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

2. Add the following entry to the "mcpServers" object (create the file with this content if it doesn't exist yet):

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

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.

<details>
<summary><strong>Command not found?</strong></summary>

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.

</details>

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

1. Open a new conversation in Claude Desktop. Look for a tools/hammer icon near the text input — this confirms the MCP server connected successfully.

2. 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:

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

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: sql (string): The SQL query to execute.

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 OK with the Hydrolix query-head's Clickhouse version if the server is healthy and can connect to Hydrolix
- Returns 503 Service Unavailable if the server cannot connect to the Hydrolix query-head

Example:
```bash
curl http://localhost:8000/health