Hydrolix MCP Server

1# Hydrolix MCP Server
2 
3<!-- mcp-name: io.github.hydrolix/mcp-hydrolix -->
4 
5[![PyPI - Version](https://img.shields.io/pypi/v/mcp-hydrolix)](https://pypi.org/project/mcp-hydrolix)
6 
7An MCP server for Hydrolix.
8 
9## Tools
10 
11* `run_select_query`
12  * Execute SQL queries on your Hydrolix cluster.
13  * Input: `sql` (string): The SQL query to execute.
14 
15* `list_databases`
16  * List all databases on your Hydrolix cluster.
17 
18* `list_tables`
19  * List all tables in a database.
20  * Input: `database` (string): The name of the database.
21 
22* `get_table_info`
23  * Get table metadata such as schema
24  * Input: `database` (string): The name of the database.
25  * Input: `table` (string): The name of the table.
26 
27## Effective Usage
28 
29Due 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:
30 
31* 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 ...")
32  - This encourages the model to use the MCP tools available and minimizes hallucinations.
33* 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.
34  - This prompts the model to write more efficient queries that take advantage of [primary key optimizations](https://hydrolix.io/blog/optimizing-latest-n-row-queries/)
35 
36### Health Check Endpoint
37 
38When running with HTTP or SSE transport, a health check endpoint is available at `/health`. This endpoint:
39- Returns `200 OK` with the Hydrolix query-head's Clickhouse version if the server is healthy and can connect to Hydrolix
40- Returns `503 Service Unavailable` if the server cannot connect to the Hydrolix query-head
41 
42Example:
43```bash
44curl http://localhost:8000/health
45# Response: OK - Connected to Hydrolix compatible with ClickHouse 24.3.1
46```
47 
48## Configuration
49 
50The 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.
51 
52The recommended way to launch the Hydrolix MCP server is via the [`uv` project manager](https://github.com/astral-sh/uv), which will manage installing all other dependencies in an isolated environment.
53 
54### Authentication
55 
56The server supports multiple authentication methods with the following precedence (highest to lowest):
57 
581. **Per-request Bearer token**: Service account token provided via `Authorization: Bearer <token>` header
592. **Per-request GET parameter**: Service account token provided via `?token=<token>` query parameter
603. **Environment-based credentials**: Credentials configured via environment variables
61   - Service account token (`HYDROLIX_TOKEN`), or
62   - Username and password (`HYDROLIX_USER` and `HYDROLIX_PASSWORD`)
63 
64When 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.
65 
66**Note: Using a service account token with a readonly role is recommended.**
67 
68MCP Server definition using username and password (JSON):
69 
70```json
71{
72  "command": "uv",
73  "args": [
74    "run",
75    "--with",
76    "mcp-hydrolix",
77    "--python",
78    "3.13",
79    "mcp-hydrolix"
80  ],
81  "env": {
82    "HYDROLIX_HOST": "<hydrolix-host>",
83    "HYDROLIX_USER": "<hydrolix-user>",
84    "HYDROLIX_PASSWORD": "<hydrolix-password>"
85  }
86}
87```
88 
89MCP Server definition using service account token (JSON):
90 
91```json
92{
93  "command": "uv",
94  "args": [
95    "run",
96    "--with",
97    "mcp-hydrolix",
98    "--python",
99    "3.13",
100    "mcp-hydrolix"
101  ],
102  "env": {
103    "HYDROLIX_HOST": "<hydrolix-host>",
104    "HYDROLIX_TOKEN": "<hydrolix-service-account-token>"
105  }
106}
107```
108 
109MCP Server definition using username and password (YAML):
110 
111```yaml
112command: uv
113args:
114- run
115- --with
116- mcp-hydrolix
117- --python
118- "3.13"
119- mcp-hydrolix
120env:
121  HYDROLIX_HOST: <hydrolix-host>
122  HYDROLIX_USER: <hydrolix-user>
123  HYDROLIX_PASSWORD: <hydrolix-password>
124```
125 
126MCP Server definition using service account token (YAML):
127 
128```yaml
129command: uv
130args:
131- run
132- --with
133- mcp-hydrolix
134- --python
135- "3.13"
136- mcp-hydrolix
137env:
138  HYDROLIX_HOST: <hydrolix-host>
139  HYDROLIX_TOKEN: <hydrolix-service-account-token>
140```
141 
142### Configuration Example (Claude Desktop)
143 
1441. Open the Claude Desktop configuration file located at:
145   - On macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
146   - On Windows: `%APPDATA%/Claude/claude_desktop_config.json`
147 
1482. Add a `mcp-hydrolix` server entry to the `mcpServers` config block to use username and password:
149 
150```json
151{
152  "mcpServers": {
153    "mcp-hydrolix": {
154      "command": "uv",
155      "args": [
156        "run",
157        "--with",
158        "mcp-hydrolix",
159        "--python",
160        "3.13",
161        "mcp-hydrolix"
162      ],
163      "env": {
164        "HYDROLIX_HOST": "<hydrolix-host>",
165        "HYDROLIX_USER": "<hydrolix-user>",
166        "HYDROLIX_PASSWORD": "<hydrolix-password>"
167      }
168    }
169  }
170}
171```
172 
173To leverage service account use the following config block:
174 
175```json
176{
177  "mcpServers": {
178    "mcp-hydrolix": {
179      "command": "uv",
180      "args": [
181        "run",
182        "--with",
183        "mcp-hydrolix",
184        "--python",
185        "3.13",
186        "mcp-hydrolix"
187      ],
188      "env": {
189        "HYDROLIX_HOST": "<hydrolix-host>",
190        "HYDROLIX_TOKEN": "<hydrolix-service-account-token>"
191      }
192    }
193  }
194}
195```
196 
1973. Update the environment variable definitions to point to your Hydrolix cluster.
198 
1994. (Recommended) Locate the command entry for `uv` and replace it with the absolute path to the `uv` executable. This ensures that the correct version of `uv` is used when starting the server. You can find this path using `which uv` or `where.exe uv`.
200 
2015. 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.
202 
203### Configuration Example (Claude Code)
204 
205To configure the Hydrolix MCP server for Claude Code, run the following command:
206 
207```bash
208claude mcp add --transport stdio hydrolix \
209  --env HYDROLIX_USER=<hydrolix-user> \
210  --env HYDROLIX_PASSWORD=<hydrolix-password> \
211  --env HYDROLIX_HOST=<hydrolix-host> \
212  --env HYDROLIX_MCP_SERVER_TRANSPORT=stdio \
213  -- uv run --with mcp-hydrolix --python 3.13 mcp-hydrolix
214```
215 
216### Environment Variables
217 
218The 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.
219 
220#### Required Variables
221* `HYDROLIX_HOST`: The hostname of your Hydrolix server
222 
223#### Authentication Variables
224At least one authentication method must be configured when using the stdio transport:
225 
226* `HYDROLIX_TOKEN`: Service account token for environment-based authentication
227* `HYDROLIX_USER` and `HYDROLIX_PASSWORD`: Username and password for environment-based authentication (both must be provided together)
228 
229In summary:
230- For stdio, you MUST use HYDROLIX_TOKEN or HYDROLIX_USER+HYDROLIX_PASS (environmental credentials)
231- For http/sse, you MAY use HYDROLIX_TOKEN or HYDROLIX_USER+HYDROLIX_PASS (environmental credentials), but you may instead use per-request credentials.
232 
233If no credentials are provided via the environment or the request, the request will fail.
234 
235#### Optional Variables
236* `HYDROLIX_PORT`: The port number of your Hydrolix server
237  * Default: `8088`
238  * Usually doesn't need to be set unless using a non-standard port
239* `HYDROLIX_VERIFY`: Enable/disable SSL certificate verification
240  * Default: `"true"`
241  * Set to `"false"` to disable certificate verification (not recommended for production)
242* `HYDROLIX_DATABASE`: Default database to use
243  *Default: None (uses server default)
244  * Set this to automatically connect to a specific database
245* `HYDROLIX_MCP_SERVER_TRANSPORT`: Sets the transport method for the MCP server.
246  * Default: `"stdio"`
247  * Valid options: `"stdio"`, `"http"`, `"sse"`. This is useful for local development with tools like MCP Inspector.
248* `HYDROLIX_MCP_BIND_HOST`: Host to bind the MCP server to when using HTTP or SSE transport
249  * Default: `"127.0.0.1"`
250  * Set to `"0.0.0.0"` to bind to all network interfaces (useful for Docker or remote access)
251  * Only used when transport is `"http"` or `"sse"`
252* `HYDROLIX_MCP_BIND_PORT`: Port to bind the MCP server to when using HTTP or SSE transport
253  * Default: `"8000"`
254  * Only used when transport is `"http"` or `"sse"`
255 
256 
257For MCP Inspector or remote access with HTTP transport:
258 
259```env
260HYDROLIX_HOST=localhost
261HYDROLIX_USER=default
262HYDROLIX_PASSWORD=myPassword
263HYDROLIX_MCP_SERVER_TRANSPORT=http
264HYDROLIX_MCP_BIND_HOST=0.0.0.0  # Bind to all interfaces
265HYDROLIX_MCP_BIND_PORT=4200  # Custom port (default: 8000)
266```
267 
268When using HTTP transport, the server will run on the configured port (default 8000). For example, with the above configuration:
269- MCP endpoint: `http://localhost:4200/mcp`
270- Health check: `http://localhost:4200/health`
271 
272#### Using Per-Request Authentication with HTTP Transport
273 
274When 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.
275 
276Example `mcpServers` configuration connecting to a remote HTTP server with per-request authentication:
277 
278```json
279{
280  "mcpServers": {
281    "mcp-hydrolix-remote": {
282      "url": "https://my-hydrolix-mcp.example.com/mcp?token=<service-account-token>"
283    }
284  }
285}
286```
287 
288Example minimal `.env` configuration for running your own HTTP server without environment credentials:
289 
290```env
291HYDROLIX_HOST=my-cluster.hydrolix.net
292HYDROLIX_MCP_SERVER_TRANSPORT=http
293```
294 
295Though 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.
296 
297Note: The bind host and port settings are only used when transport is set to "http" or "sse".
298