Hydrolix MCP Server

offiziell

Hydrolix Time-Series-Datalake-Integration, die Schemaerkundung und Abfragefunktionen für LLM-basierte Workflows bereitstellt.

GitHub

Dokumentation

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-Anmeldeinformationen — Ihren Cluster-Hostnamen sowie entweder einen Benutzernamen/ein Passwort oder ein Dienstkonto-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

Ö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
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 Anmeldeinformationen.

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

[!TIPP] 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.

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

Befehl nicht gefunden?

Claude Desktop startet ohne den PATH Ihrer Shell, sodass die Binärdatei möglicherweise nicht gefunden wird, selbst wenn sie installiert ist. Ermitteln 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 zu übernehmen.

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

Ö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 wurde.
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.

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 Folgendes 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 derselben Eingabeaufforderung:

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-Datei für eine Ein-Klick-Installation. Falls Sie den UI-Workflow bevorzugen, öffnen Sie die Befehlspalette (Cmd+Shift+P / Strg+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 (Zeichenkette): 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 (Zeichenkette): Der Name der Datenbank.
get_table_info
- Ruft Tabellenmetadaten wie das Schema ab.
- Eingabe: database (Zeichenkette): Der Name der Datenbank.
- Eingabe: table (Zeichenkette): 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 Eingabeaufforderungen 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 Eingabeaufforderungen an (z. B. "Zwischen dem 5. Dezember 2023 und dem 18. Januar 2024, ...") und fordern Sie ausdrücklich an, dass die Ausgabe nach Zeitstempel geordnet wird.
- Dies veranlasst das Modell, effizientere Abfragen zu schreiben, die die Primärschlüssel-Optimierungen nutzen.

Health-Check-Endpunkt

Bei Verwendung des HTTP- oder SSE-Transports 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 niedrigste):

Bearer-Token pro Anfrage: Dienstkonto-Token, bereitgestellt über den Authorization: Bearer <token>-Header
GET-Parameter pro Anfrage: Dienstkonto-Token, bereitgestellt über den ?token=<token>-Abfrageparameter
Umgebungsbasierte Anmeldeinformationen: Über Umgebungsvariablen konfigurierte Anmeldeinformationen
- Dienstkonto-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 der HTTP- oder SSE-Transportmodi verfügbar.

Hinweis: Die Verwendung eines Dienstkonto-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 Dienstkonto-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 Dienstkonto-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)

Ö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
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 Dienstkonto 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>"
      }
    }
  }
}

Aktualisieren Sie die Definitionen der Umgebungsvariablen, um auf Ihren Hydrolix-Cluster zu verweisen.
(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 können diesen Pfad mit which uvx oder where.exe uvx finden.
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 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 berücksichtigt, sollte aber durch HYDROLIX_URL ersetzt werden.

Wenn HYDROLIX_MCP_SERVER_TRANSPORT auf http oder sse gesetzt ist, ist HYDROLIX_URL speziell erforderlich (der OAuth-Metadaten-Endpunkt kündigt ihn an). HYDROLIX_HOST allein ist für diese Transporte nicht ausreichend.

Endpunkt-Überschreibungen

Diese überschreiben die von HYDROLIX_URL abgeleiteten Werte. Sie sind nützlich für Bereitstellungen innerhalb des Clusters, bei denen der HTTP-Abfrageendpunkt und die Versions-API unter unterschiedlichen internen Hostnamen oder Ports erreichbar sind. Überschreibungsrangfolge: explizite neue Variable > veralteter Alias > HYDROLIX_URL-abgeleitet > fester Standard.

HYDROLIX_HTTP_QUERY_HOST / HYDROLIX_HTTP_QUERY_PORT / HYDROLIX_HTTP_QUERY_SECURE: Überschreiben den ClickHouse-HTTP-Abfrageendpunkt.
HYDROLIX_VERSION_API_HOST / HYDROLIX_VERSION_API_PORT / HYDROLIX_VERSION_API_SECURE: Überschreiben den REST /version-Probe-Endpunkt. HYDROLIX_VERSION_API_SECURE erbt standardmäßig vom aufgelösten sicheren Wert der HTTP-Abfrage.

Veraltete Variablen

Die folgenden werden während des Übergangszeitraums weiterhin berücksichtigt, aber in einer zukünftigen Version entfernt. Migrieren Sie bei Gelegenheit:

Veraltet	Ersatz
`HYDROLIX_HOST`	`HYDROLIX_URL` (bevorzugt) oder `HYDROLIX_HTTP_QUERY_HOST`
`HYDROLIX_PORT`	`HYDROLIX_HTTP_QUERY_PORT`
`HYDROLIX_SECURE`	`HYDROLIX_HTTP_QUERY_SECURE`
`HYDROLIX_API_HOST`	`HYDROLIX_VERSION_API_HOST`
`HYDROLIX_API_PORT`	`HYDROLIX_VERSION_API_PORT`

Externe Betreiber, die eine dieser Variablen verwenden, sehen eine einmalige Startwarnung, die zur Migration auf HYDROLIX_URL rät. Cluster-interne (o6r-verwaltete) Bereitstellungen sehen diese Warnung nicht; ihre Migration wird von der Plattform übernommen.

Authentifizierungsvariablen

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

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

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

Optionale Variablen

HYDROLIX_VERIFY: SSL-Zertifikatsprüfung aktivieren/deaktivieren
- Standard: "true"
- Auf "false" setzen, um die Zertifikatsprüfung zu deaktivieren (nicht für Produktion empfohlen)
HYDROLIX_DATABASE: Zu verwendende Standarddatenbank
- Standard: Keine (verwendet Serverstandard)
- Hiermit wird automatisch eine Verbindung zu einer bestimmten Datenbank hergestellt
HYDROLIX_MCP_SERVER_TRANSPORT: Legt die Transportmethode für den MCP-Server fest.
- Standard: "stdio"
- Gültige Optionen: "stdio", "http", "sse". Nützlich für die lokale Entwicklung mit Tools wie MCP Inspector.
HYDROLIX_MCP_BIND_HOST: Host, an den der MCP-Server bei Verwendung von HTTP- oder SSE-Transport gebunden wird
- Standard: "127.0.0.1"
- Auf "0.0.0.0" setzen, um an alle Netzwerkschnittstellen zu binden (nützlich für Docker oder Fernzugriff)
- Wird nur verwendet, wenn der Transport "http" oder "sse" ist
HYDROLIX_MCP_BIND_PORT: Port, an den der MCP-Server bei Verwendung von HTTP- oder SSE-Transport gebunden wird
- Standard: "8000"
- Wird nur verwendet, wenn der Transport "http" oder "sse" ist
HYDROLIX_MAX_RAW_TIMERANGE: Maximaler Zeitbereich in Sekunden, der für Abfragen auf Nicht-Summary-Tabellen erlaubt ist
- Standard: 21600 (6 Stunden)
- Abfragen auf Summary-Tabellen sind von dieser Begrenzung nicht betroffen

Für MCP Inspector oder Fernzugriff mit HTTP-Transport:

HYDROLIX_URL=https://my-cluster.hydrolix.net
HYDROLIX_USER=default
HYDROLIX_PASSWORD=myPassword
HYDROLIX_MCP_SERVER_TRANSPORT=http
HYDROLIX_MCP_BIND_HOST=0.0.0.0  # Bind to all interfaces
HYDROLIX_MCP_BIND_PORT=4200  # Custom port (default: 8000)

Bei Verwendung von HTTP-Transport läuft der Server auf dem konfigurierten Port (Standard 8000). Zum Beispiel mit der obigen Konfiguration:

MCP-Endpunkt: http://localhost:4200/mcp
Health-Check: http://localhost:4200/health

Verwendung von Authentifizierung pro Anfrage mit HTTP-Transport

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

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

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

Minimale Beispielkonfiguration für .env zum Ausführen eines eigenen HTTP-Servers ohne Umgebungsanmeldeinformationen:

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-Anfragen. Wenn dies möglich ist, empfehlen wir, den MCP-Client so zu konfigurieren, dass ein Dienstkonto-Token aus Sicherheitsgründen über den Authorization: Bearer <sa-token-here>-Header anstelle eines Abfrageparameters übergeben wird.

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

End-to-End-Tests

Eine separate Suite unter tests/e2e/ stellt den lokalen Arbeitsbaum in einem Live- Hydrolix-Kubernetes-Cluster bereit und führt Smoke-Tests der MCP-Tools gegen den laufenden Pod durch. Sie ist von Standard-Testläufen und vom Pre-Push-Hook ausgeschlossen; die Ausführung erfordert explizites Opt-in über den end_to_end-pytest-Marker sowie Anmeldeinformationen. Siehe tests/e2e/README.md für das Runbook.