Hydrolix

Hydrolix MCP Server

Ein MCP-Server für Hydrolix.

Schnellstart

In wenigen Minuten einsatzbereit. Dieser Abschnitt behandelt Claude Desktop und Claude Code.

Schritt 1 — Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass Sie Folgendes haben:

• Hydrolix-Anmeldedaten — Ihren Cluster-Hostnamen sowie entweder einen Benutzernamen/ein Passwort oder ein Service-Account-Token. Wenn Sie diese nicht haben, fragen Sie Ihren Hydrolix-Administrator.
• Claude Desktop — herunterladen von claude.ai/download.

Schritt 2 — Den MCP-Server installieren

Wählen Sie die Methode, die zu Ihrer Umgebung passt:

Option A: Mit uv (empfohlen)

uv verwaltet Python automatisch und lädt mcp-hydrolix bei Bedarf herunter, sodass kein separater Installationsschritt erforderlich ist. Wenn Sie uv nicht haben, installieren Sie es:

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: Mit pip

Erfordert Python 3.13+. Wenn Sie Python installieren müssen, laden Sie es von python.org herunter.

pip install mcp-hydrolix

Schritt 3 — Claude Desktop konfigurieren

1. Öffnen Sie die Claude-Desktop-Konfigurationsdatei:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

2. Fügen Sie den folgenden Eintrag zum "mcpServers"-Objekt hinzu (erstellen Sie die Datei mit diesem Inhalt, falls sie noch nicht existiert):

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

Ersetzen Sie <your-hydrolix-hostname>, <your-username> und <your-password> mit Ihren tatsächlichen Anmeldedaten.

[!NOTE] Wenn Sie Option B (pip) verwendet haben, verwenden Sie "command": "mcp-hydrolix" ohne ein "args"-Feld.

[!TIP] Wenn die Datei bereits andere Einträge enthält, fügen Sie den "mcp-hydrolix"-Block innerhalb des vorhandenen "mcpServers"-Objekts hinzu, anstatt die gesamte Datei zu ersetzen.

[!NOTE] Wenn Sie sich mit einem Service-Account-Token anstelle von Benutzername/Passwort authentifizieren, siehe Authentifizierung.

Befehl nicht gefunden?

Claude Desktop startet ohne die PATH-Umgebung Ihrer Shell, daher kann es das Binärprogramm möglicherweise nicht finden, selbst wenn es installiert ist. Finden Sie den vollständigen Pfad und verwenden Sie ihn als "command"-Wert in der Konfiguration.

Option A (uv): uvx finden:

• macOS / Linux: which uvx
• Windows: where.exe uvx

Option B (pip): mcp-hydrolix finden:

• macOS / Linux: which mcp-hydrolix
• Windows: where.exe mcp-hydrolix

Wenn which/where.exe nichts zurückgibt, ist das Binärprogramm nicht in Ihrem PATH. Die sauberste Lösung ist der Wechsel zu Option A (uv), die die Python-Umgebung und den PATH für Sie verwaltet.

Schritt 4 — Claude Desktop neu starten

Starten Sie die App neu, um die Konfiguration anzuwenden.

macOS / Windows-Benutzer: Stellen Sie sicher, dass Sie Claude vollständig beenden, bevor Sie neu starten. Drücken Sie auf macOS Cmd+Q oder klicken Sie mit der rechten Maustaste auf das Dock-Symbol und wählen Sie Beenden. Verwenden Sie unter Windows das Symbol im System-Tray.

Schritt 5 — Überprüfen, dass es funktioniert

1. Öffnen Sie eine neue Konversation in Claude Desktop. Suchen Sie nach einem Werkzeuge/Hammer-Symbol in der Nähe der Texteingabe — dies bestätigt, dass der MCP-Server erfolgreich verbunden wurde.

2. Versuchen Sie diese Eingabeaufforderung, um zu bestätigen, dass alles funktioniert:

   Listen Sie mit Ihren Hydrolix-MCP-Tools die verfügbaren Datenbanken auf.

Claude sollte das list_databases-Tool aufrufen und eine Liste der Datenbanken aus Ihrem Cluster zurückgeben.

---

Stattdessen Claude Code verwenden?

Wenn Sie die Befehlszeile bevorzugen, stellen Sie sicher, dass uv installiert ist (Option A aus Schritt 2), und führen Sie dann aus:

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

Öffnen Sie dann Claude Code und testen Sie mit derselben Eingabeaufforderung:

Listen Sie mit Ihren Hydrolix-MCP-Tools die verfügbaren Datenbanken auf.

Stattdessen VS Code verwenden?

Klicken Sie auf das In VS Code installieren-Abzeichen oben in dieser README für eine Installation mit einem Klick. Wenn Sie den UI-Ablauf bevorzugen, öffnen Sie die Befehlspalette (Cmd+Shift+P / Ctrl+Shift+P), führen Sie MCP: Server hinzufügen aus, wählen Sie Befehl (stdio) und verwenden Sie den uvx ...-Befehl und den env-Block aus Schritt 3 erneut.

Werkzeuge

• run_select_query

  • SQL-Abfragen auf Ihrem Hydrolix-Cluster ausführen.
  • Eingabe: query (Zeichenfolge): Die auszuführende SQL-Abfrage.
  • Eingabe: max_cells (Ganzzahl, optional): Ergebniszellenbudget (Zeilen × Spalten); wenn der Server ein Limit festlegt, kann ein Aufrufer es nur senken.
  • Eingabe: purpose (Zeichenfolge, erforderlich): Warum die Abfrage ausgeführt wird; wird mit der Abfrage als hdx_query_comment aufgezeichnet.
  • Eine abschließende FORMAT-Klausel wird entfernt; der Server wählt das Drahtformat.

• list_databases

  • Alle Datenbanken auf Ihrem Hydrolix-Cluster auflisten.

• list_tables

  • Alle Tabellen in einer Datenbank auflisten.
  • Eingabe: database (Zeichenfolge): Der Name der Datenbank.

• get_table_info

  • Tabellenmetadaten wie Schema abrufen.
  • Eingabe: database (Zeichenfolge): Der Name der Datenbank.
  • Eingabe: table (Zeichenfolge): Der Name der Tabelle.

Effektive Nutzung

Aufgrund der großen Vielfalt an LLM-Architekturen werden nicht alle Modelle die oben genannten Werkzeuge proaktiv verwenden, und nur wenige werden sie ohne Anleitung effektiv nutzen, selbst mit den sorgfältig erstellten Werkzeugbeschreibungen, die dem Modell bereitgestellt werden. Um die besten Ergebnisse mit Ihrem Modell bei Verwendung des Hydrolix-MCP-Servers zu erzielen, empfehlen wir Folgendes:

• Beziehen Sie sich in Ihren Eingabeaufforderungen namentlich auf Ihre Hydrolix-Datenbank und fordern Sie die Werkzeugnutzung an (z. B. „Bitte verwenden Sie MCP-Tools für den Zugriff auf meine Hydrolix-Datenbank, um ...")
  • Dies ermutigt das Modell, die verfügbaren MCP-Tools zu verwenden und minimiert Halluzinationen.
• Fügen Sie Zeiträume in Ihre Eingabeaufforderungen ein (z. B. „Zwischen dem 5. Dezember 2023 und dem 18. Januar 2024, ...") und fordern Sie ausdrücklich an, dass die Ausgabe nach Zeitstempel sortiert wird.
  • Dies veranlasst das Modell, effizientere Abfragen zu schreiben, die Primärschlüssel-Optimierungen nutzen.

Health-Check-Endpunkt

Bei Verwendung von HTTP- oder SSE-Transport ist ein Health-Check-Endpunkt unter /health verfügbar. Dieser Endpunkt:

• Gibt 200 OK mit der Clickhouse-Version des Hydrolix-Abfrageknotens zurück, wenn der Server fehlerfrei ist und eine Verbindung zu Hydrolix herstellen kann
• Gibt 503 Service Unavailable zurück, wenn der Server keine Verbindung zum Hydrolix-Abfrageknoten herstellen kann

Beispiel:

curl http://localhost:8000/health
# Response: OK - Connected to Hydrolix compatible with ClickHouse 24.3.1

Konfiguration

Der Hydrolix-MCP-Server wird mit einem standardmäßigen MCP-Servereintrag konfiguriert. Konsultieren Sie die Dokumentation Ihres Clients für spezifische Anweisungen, wo MCP-Server zu finden oder zu deklarieren sind. Ein Beispiel-Setup mit Claude Desktop ist unten dokumentiert.

Die empfohlene Methode zum Starten des Hydrolix-MCP-Servers ist über den uv-Projektmanager, der die Installation aller anderen Abhängigkeiten in einer isolierten Umgebung verwaltet.

Authentifizierung

Der Server unterstützt mehrere Authentifizierungsmethoden mit folgender Priorität (höchste zu niedrigste):

1. Bearer-Token pro Anfrage: Service-Account-Token, bereitgestellt über den Authorization: Bearer <token>-Header
2. GET-Parameter pro Anfrage: Service-Account-Token, bereitgestellt über den ?token=<token>-Abfrageparameter
3. Umgebungsbasierte Anmeldedaten: Über Umgebungsvariablen konfigurierte Anmeldedaten
   • Service-Account-Token (HYDROLIX_TOKEN), oder
   • Benutzername und Passwort (HYDROLIX_USER und HYDROLIX_PASSWORD)

Wenn mehrere Authentifizierungsmethoden konfiguriert sind, verwendet der Server die erste verfügbare Methode in der obigen Prioritätsreihenfolge. Die Authentifizierung pro Anfrage ist nur bei Verwendung von HTTP- oder SSE-Transportmodi verfügbar. Die ?token=-Form existiert für Clients, die keine Header senden können; setzen Sie HYDROLIX_ALLOW_TOKEN_QUERY_PARAM=false auf Bereitstellungen, bei denen jeder Client den Authorization-Header sendet (siehe Anmeldedaten pro Anfrage).

Hinweis: Die Verwendung eines Service-Account-Tokens mit einer Nur-Lese-Rolle wird empfohlen.

MCP-Serverdefinition mit Benutzername und Passwort (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-Serverdefinition mit Service-Account-Token (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-Serverdefinition mit Benutzername und Passwort (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-Serverdefinition mit Service-Account-Token (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>

Konfigurationsbeispiel (Claude Desktop)

1. Öffnen Sie die Claude-Desktop-Konfigurationsdatei unter:

   • Auf macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Auf Windows: %APPDATA%/Claude/claude_desktop_config.json

2. Fügen Sie einen mcp-hydrolix-Servereintrag zum mcpServers-Konfigurationsblock hinzu, um Benutzername und Passwort zu verwenden:

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

Um ein Service-Konto zu nutzen, verwenden Sie den folgenden Konfigurationsblock:

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

3. Aktualisieren Sie die Definitionen der Umgebungsvariablen, um auf Ihren Hydrolix-Cluster zu verweisen.

4. (Empfohlen) Suchen Sie den Befehlseintrag für uvx und ersetzen Sie ihn durch den absoluten Pfad zur uvx-ausführbaren Datei. Dies stellt sicher, dass die korrekte Version von uvx beim Starten des Servers verwendet wird. Sie können diesen Pfad mit which uvx oder where.exe uvx finden.

5. Starten Sie Claude Desktop neu, um die Änderungen anzuwenden. Wenn Sie Windows verwenden, stellen Sie sicher, dass Claude vollständig beendet ist, indem Sie den Client über das System-Tray-Symbol schließen.

Konfigurationsbeispiel (Claude Code)

Um den Hydrolix-MCP-Server für Claude Code zu konfigurieren, führen Sie den folgenden Befehl aus:

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

Umgebungsvariablen

Die folgenden Variablen werden zur Konfiguration der Hydrolix-Verbindung verwendet. Diese Variablen können über den MCP-Konfigurationsblock (wie oben gezeigt), eine .env-Datei oder traditionelle Umgebungsvariablen bereitgestellt werden.

Erforderliche Variablen

Sie MÜSSEN eine der folgenden Optionen festlegen, um den Cluster zu identifizieren:

• HYDROLIX_URL (empfohlen): Die kanonische öffentliche URL Ihres Hydrolix-Clusters, z. B. https://mycluster.hydrolix.live. Für typische Bereitstellungen außerhalb des Clusters ist diese einzelne Variable ausreichend — sie liefert den Host, den Port (schema-standard 443/80) und die TLS-Einstellungen sowohl für den HTTP-Abfrageendpunkt als auch für den REST-/version-Probe.
• HYDROLIX_HOST (veraltet): Der Hostname Ihres Hydrolix-Servers. Wird aus Gründen der Abwärtskompatibilität weiterhin unterstützt, sollte aber durch HYDROLIX_URL ersetzt werden.

Wenn HYDROLIX_MCP_SERVER_TRANSPORT http oder sse ist, ist HYDROLIX_URL spezifisch erforderlich (ein kommender OAuth-Metadatenendpunkt würde es ankündigen). HYDROLIX_HOST allein ist für diese Transporte nicht ausreichend.

Authentifizierungsvariablen

Mindestens eine Authentifizierungsmethode muss konfiguriert sein, wenn der stdio-Transport verwendet wird:

• HYDROLIX_TOKEN: Service-Account-Token für umgebungsbasierte Authentifizierung
• HYDROLIX_USER und HYDROLIX_PASSWORD: Benutzername und Passwort für umgebungsbasierte Authentifizierung (beide müssen zusammen angegeben werden)

Zusammenfassung:

• Für stdio MÜSSEN Sie HYDROLIX_TOKEN oder HYDROLIX_USER+HYDROLIX_PASS verwenden (Umgebungsanmeldedaten)
• Für http/sse KÖNNEN Sie HYDROLIX_TOKEN oder HYDROLIX_USER+HYDROLIX_PASS verwenden (Umgebungsanmeldedaten), aber Sie können stattdessen Anmeldedaten pro Anfrage verwenden.

Wenn keine Anmeldedaten über die Umgebung oder die Anfrage bereitgestellt werden, schlägt die Anfrage fehl.

Verwendung der Authentifizierung pro Anfrage mit HTTP-Transport

Bei Verwendung von HTTP- oder SSE-Transport können Sie umgebungsbasierte Anmeldedaten weglassen und stattdessen die Authentifizierung pro Anfrage bereitstellen. Dies ist nützlich für Mehrbenutzerszenarien oder mit Clients, die die lokale Ausführung von MCP-Servern nicht unterstützen.

Beispiel für eine mcpServers-Konfiguration, die eine Verbindung zu einem entfernten HTTP-Server mit Authentifizierung pro Anfrage herstellt:

{
  "mcpServers": {
    "mcp-hydrolix-remote": {
      "url": "https://my-hydrolix-mcp.example.com/mcp?token=<service-account-token>"
    }
  }
}

Beispiel für eine minimale .env-Konfiguration zum Ausführen Ihres eigenen HTTP-Servers ohne Umgebungsanmeldedaten:

HYDROLIX_URL=https://my-cluster.hydrolix.net
HYDROLIX_MCP_SERVER_TRANSPORT=http

Obwohl nicht Teil der MCP-Spezifikation, erlauben viele MCP-Clients das Hinzufügen von Headern zu MCP-ausgestellten Anfragen. Wenn dies möglich ist, empfehlen wir, den MCP-Client so zu konfigurieren, dass ein Service-Account-Token über den Authorization: Bearer <sa-token-here>-Header anstelle eines Abfrageparameters für mehr Sicherheit übergeben wird.

Hinweis: Die Bind-Host- und Port-Einstellungen werden nur verwendet, wenn der Transport auf „http" oder „sse" gesetzt ist.

Optionale Variablen

Siehe docs/CONFIG.md für Endpunkt-Überschreibungen, veraltete Variablenaliase und den vollständigen Satz optionaler Tuning-Variablen (Timeouts, Abfrage-SETTINGS-Überschreibungen, Ergebnisabschneidung, HTTP/SSE-Worker-Tuning, Proxy, Metriken und Notausgänge).

Maintainer

Aufgaben, die operative Berechtigungen erfordern — das Ausführen der End-to-End-Suite gegen einen Live-Hydrolix-Cluster sowie das Erstellen eines Releases — sind separat dokumentiert in MAINTAINERS.md.