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

Stellen Sie vor dem Start sicher, dass Sie Folgendes haben:

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

Schritt 2 — MCP-Server installieren

Wählen Sie die Methode, die zu Ihrem Setup passt:

Option A: Verwendung von uv (empfohlen)

uv verwaltet Python automatisch und lädt mcp-hydrolix bei Bedarf herunter, sodass kein separater Installationsschritt erforderlich ist. Falls 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: Verwendung von pip

Erfordert Python 3.13+. Falls 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> durch Ihre tatsächlichen Anmeldedaten.

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

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

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

Befehl nicht gefunden?

Claude Desktop startet ohne den PATH Ihrer Shell, daher findet es die Binärdatei möglicherweise nicht, selbst wenn sie installiert ist. Finden Sie den vollständigen Pfad und verwenden Sie ihn als Wert für "command" in der Konfiguration.

Option A (uv): Finden Sie uvx:

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

Option B (pip): Finden Sie mcp-hydrolix:

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

Falls which/where.exe nichts zurückgibt, befindet sich die Binärdatei nicht in Ihrem PATH. Die einfachste 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 es neu starten. Drücken Sie unter macOS Cmd+Q oder klicken Sie mit der rechten Maustaste auf das Dock-Symbol und wählen Sie Beenden. Verwenden Sie unter Windows das Taskleistensymbol.

Schritt 5 — Funktionsfähigkeit überprüfen

1. Öffnen Sie eine neue Konversation in Claude Desktop. Achten Sie auf ein Werkzeug-/Hammer-Symbol in der Nähe der Texteingabe — dies bestätigt, dass der MCP-Server erfolgreich verbunden ist.

2. Versuchen Sie diesen Prompt, 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.

---

Verwenden Sie stattdessen Claude Code?

Falls 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 es mit demselben Prompt:

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

Verwenden Sie stattdessen VS Code?

Klicken Sie auf das In VS Code installieren-Abzeichen oben in dieser README für eine Ein-Klick-Installation. Falls Sie den UI-Workflow 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.

Tools

• run_select_query

  • Führen Sie SQL-Abfragen auf Ihrem Hydrolix-Cluster aus.
  • Eingabe: sql (string): Die auszuführende SQL-Abfrage.

• list_databases

  • Listet alle Datenbanken auf Ihrem Hydrolix-Cluster auf.

• list_tables

  • Listet alle Tabellen in einer Datenbank auf.
  • Eingabe: database (string): Der Name der Datenbank.

• get_table_info

  • Ruft Tabellenmetadaten wie das Schema ab.
  • Eingabe: database (string): Der Name der Datenbank.
  • Eingabe: table (string): Der Name der Tabelle.

Effektive Nutzung

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

• Verweisen Sie namentlich auf Ihre Hydrolix-Datenbank und fordern Sie die Tool-Nutzung in Ihren Prompts an (z. B. "Verwenden Sie MCP-Tools, um auf meine Hydrolix-Datenbank zuzugreifen, bitte ...")
  • Dies ermutigt das Modell, die verfügbaren MCP-Tools zu nutzen und minimiert Halluzinationen.
• Geben Sie Zeitbereiche in Ihren Prompts an (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 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-Abfragekopfes 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-Abfragekopf 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 über einen standardmäßigen MCP-Server-Eintrag 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.

Der empfohlene Weg, den Hydrolix MCP-Server zu starten, 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 der folgenden Rangfolge (höchste zu niedrigster):

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 oben genannten Rangfolge. Die Authentifizierung pro Anfrage ist nur bei Verwendung von HTTP- oder SSE-Transportmodi verfügbar.

Hinweis: Die Verwendung eines Service-Account-Tokens mit einer schreibgeschützten Rolle wird empfohlen.

MCP-Server-Definition 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-Server-Definition 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-Server-Definition 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-Server-Definition 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:

   • Unter macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Unter 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-Account 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 ausführbaren Datei uvx. Dies stellt sicher, dass beim Starten des Servers die richtige Version von uvx verwendet wird. Sie finden diesen Pfad mit which uvx oder where.exe uvx.

5. Starten Sie Claude Desktop neu, um die Änderungen zu übernehmen. Wenn Sie Windows verwenden, stellen Sie sicher, dass Claude vollständig beendet ist, indem Sie den Client über das Taskleistensymbol 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 verwendet, um die Hydrolix-Verbindung zu konfigurieren. 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 reicht diese einzelne Variable aus — sie liefert Host, Port (Schema-Standard 443/80) und 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 auf http oder sse gesetzt ist, ist HYDROLIX_URL speziell erforderlich (ein zukünftiger OAuth-Metadaten-Endpunkt würde dies ankündigen). HYDROLIX_HOST allein reicht für diese Transporte nicht aus.

Authentifizierungsvariablen

Bei Verwendung des stdio-Transports muss mindestens eine Authentifizierungsmethode konfiguriert sein:

• 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 (Umgebungsanmeldedaten) verwenden.
• Für http/sse KÖNNEN Sie HYDROLIX_TOKEN oder HYDROLIX_USER+HYDROLIX_PASS (Umgebungsanmeldedaten) verwenden, aber Sie können stattdessen auch Anmeldedaten pro Anfrage nutzen.

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 bei 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-gesendeten Anfragen. Wenn dies möglich ist, empfehlen wir, den MCP-Client so zu konfigurieren, dass er ein Service-Account-Token über den Authorization: Bearer <sa-token-here>-Header anstelle eines Abfrageparameters übergibt, um die Sicherheit zu erhöhen.

Hinweis: Die Einstellungen für Bind-Host und -Port 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 Optimierungsvariablen (Timeouts, Abfrage-SETTINGS-Überschreibungen, Ergebniskürzung, HTTP/SSE-Worker-Optimierung, Proxy, Metriken und Escape-Klappen).

Betreuer

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