ClickHouse

offiziell

Fragen Sie Ihren ClickHouse-Datenbankserver ab.

GitHub
903

Was kann man mit ClickHouse MCP machen?

  • SQL-Abfragen ausführen — Bitte den Assistenten, schreibgeschützte SQL-Abfragen auf deinem ClickHouse-Cluster mit run_query auszuführen und optional Werte über params zu binden.
  • Datenbanken auflisten — Lass den Assistenten mit list_databases alle Datenbanken auf dem Cluster auflisten.
  • Tabellen mit Paginierung durchsuchen — Liste Tabellen in einer database auf, filtere mit like/not_like und blättere mit page_size und page_token durch die Ergebnisse.
  • Tabellenschemas untersuchen — Rufe Spaltenmetadaten und create_table_query für Tabellen ab oder setze include_detailed_columns auf false, um kompaktere Antworten zu erhalten.
  • Abfragen vorab prüfen — Führe DESCRIBE (<query>) oder EXPLAIN ESTIMATE <query> über run_query aus, um Ausgabespalten oder geschätzte Lesevorgänge vor der Ausführung anzuzeigen.
  • Dateien und URLs über chDB abfragen — Verwende run_chdb_select_query, um Dateien, URLs und Datenbanken über die eingebettete Engine von chDB ohne ETL abzufragen.

Dokumentation

ClickHouse MCP Server

PyPI - Version

Ein MCP-Server für ClickHouse.

mcp-clickhouse MCP server

Der Server implementiert MCP 2026-07-28 und unterstützt Legacy-Initialize-Handshakes von 2024-11-05 bis 2025-11-25. Moderne Clients verwenden sitzungslose Anfragen und server/discover. Bestehende Clients können weiterhin das Legacy-Protokoll aushandeln.

[!NOTE] HTTP-Anfragen ohne MCP-Protocol-Version werden über die Legacy-Verarbeitung geleitet, damit Clients von vor 2025-06-18 weiterhin eine Verbindung herstellen können. MCP 2026-07-28 erlaubt dieses Verhalten auf Servern, die solche Clients unterstützen. Moderne Clients sollten den Header bei jeder POST-Anfrage senden.

Funktionen

ClickHouse-Tools

ClickHouse-Toolantworten sind JSON-kodierte Zeichenfolgen. Ganzzahlen außerhalb [-9007199254740991, 9007199254740991] werden als Dezimalzeichenfolgen zurückgegeben, um exakte Werte in JavaScript-Clients zu erhalten. Dies gilt für Abfragezeilen und ganzzahlige Tabellenmetadaten. Ganzzahlen im sicheren Wertebereich und boolesche Werte behalten ihre JSON-Typen bei.

  • run_query

    • SQL-Abfragen auf Ihrem ClickHouse-Cluster ausführen.
    • Eingabe: query (string): Die auszuführende SQL-Abfrage.
    • Optionale Eingabe: params (object): Benannte Werte für ClickHouse-{name:Type}-Platzhalter. Siehe Abfrageparameter.
    • Abfragen werden standardmäßig im schreibgeschützten Modus ausgeführt (CLICKHOUSE_ALLOW_WRITE_ACCESS=false), Schreibvorgänge können bei Bedarf jedoch ausdrücklich aktiviert werden.
    • Auch DESCRIBE (<query>) und EXPLAIN ESTIMATE <query> werden hier ausgeführt und sind optionale Möglichkeiten, das Ergebnisschema einer Abfrage oder die geschätzten Lesevorgänge zu prüfen. Siehe Eine Abfrage vor der Ausführung prüfen.

  • list_databases

    • Alle Datenbanken auf Ihrem ClickHouse-Cluster auflisten.

  • list_tables

    • Tabellen in einer Datenbank mit Paginierung auflisten.
    • Erforderliche Eingabe: database (string).
    • Optionale Eingaben:
      • like / not_like (string): LIKE- oder NOT LIKE-Filter auf Tabellennamen anwenden.
      • page_token (string): Einmalig verwendbares Token, das von einem vorherigen Aufruf zurückgegeben wurde. Es bleibt bis zu einer Stunde gültig.
      • page_size (int, default 50): Anzahl der pro Seite zurückgegebenen Tabellen; muss größer als 0 sein.
      • include_detailed_columns (bool, default true): Wenn false, werden Spaltenmetadaten für kompaktere Antworten ausgelassen, während das vollständige create_table_query erhalten bleibt.
    • Antwortstruktur:
      • tables: Array von Tabellenobjekten für die aktuelle Seite.
      • next_page_token: Diesen einmalig verwendbaren Wert vor Ablauf zurückgeben, um die nächste Seite abzurufen, oder null, wenn keine weiteren Tabellen vorhanden sind.
      • total_tables: Gesamtzahl der Tabellen, die den angegebenen Filtern entsprechen.

Agents-Schema-Ermittlung

Die Serveranweisungen empfehlen, das kanonische AGENTS.ROOT bis run_query von Agents Schema zu lesen, wenn list_databases eine AGENTS-Datenbank erkennen lässt, bevor analytisches SQL geschrieben wird. Dies ist eine Anleitung für den Agenten: Es werden keine Metadaten automatisch abgerufen, die Toolergebnisse bleiben unverändert und die bestehenden ClickHouse-Berechtigungen gelten weiterhin. Wenn AGENTS.ROOT fehlt oder nicht zugänglich ist, bleiben die normale Ermittlung und Abfragen verfügbar.

Abfrageparameter

Werte werden getrennt vom SQL über das optionale Objekt params übergeben:

{
  "query": "SELECT {id:UInt32} AS id, {name:String} AS name",
  "params": {"id": 13, "name": "O'Reilly"}
}

Verwenden Sie ClickHouse-{name:Type}-Platzhalter ohne Anführungszeichen. Die öffnende geschweifte Klammer, der Name und der Doppelpunkt müssen direkt aneinander anschließen, wie in {id:UInt32}. Leerzeichen nach dem Doppelpunkt und innerhalb des Typs werden unterstützt, wie in {id: UInt32} und {amount:Decimal(18, 4)}. Für die Kompatibilität mit allen unterstützten Treiberversionen müssen Namen mit einem Buchstaben oder Unterstrich beginnen und dürfen nur Buchstaben, Ziffern und Unterstriche enthalten. Python-artige %s- oder %(name)s-Formatierung sowie die rohen Binärparameter $name$ des Treibers werden nicht unterstützt. Aufrufe, die nur query enthalten, funktionieren weiterhin. Wird params weggelassen, null übergeben oder ein leeres Objekt übergeben, bleibt die Abfrage ungebunden.

Parameterwerte können JSON-Zeichenfolgen, Zahlen, boolesche Werte, null oder Arrays sein, sofern sie dem deklarierten ClickHouse-Typ entsprechen:

  • Verwenden Sie null mit einem Typ Nullable(...).
  • Übergeben Sie exakte Ganzzahlen außerhalb des sicheren JavaScript-Wertebereichs als Dezimalzeichenfolgen, zum Beispiel "18446744073709551615" mit {id:UInt64}. Datumsangaben, Zeitstempel und exakte Dezimalzahlen können ebenfalls als Zeichenfolgen mit dem entsprechenden ClickHouse-Typ übergeben werden.
  • Binden Sie Vektoren als einzelnes Array, zum Beispiel {vector:Array(Float32)} mit "params": {"vector": [0.25, 0.5, 0.75]}.
  • Nullwerte in Arrays hängen vom installierten Treiber ab. Sie funktionieren mit clickhouse-connect 1.8.0, schlagen jedoch mit der unterstützten Mindestversion 1.0.0 fehl.
  • JSON-Listen und -Objekte können nicht an ClickHouse-Typen Tuple und Map gebunden werden.

Fehlende Werte und inkompatible Typen führen zu Abfragefehlern. Bei nicht leerem params wird eine Abfrage mit vielen nicht abgeschlossenen {name:-Platzhalteranfängen abgelehnt, auch wenn platzhalterähnlicher Text in Kommentaren oder Zeichenfolgenliteralen vorkommt. Parametrisierte Abfragen unterliegen denselben Schreibschutzregeln, Zeitlimits und Abbruchbedingungen und verwenden dieselbe JSON-Ergebniskodierung wie andere Abfragen.

Parameterwerte erscheinen nicht in den normalen SQL-Protokollmeldungen des MCP-Servers, bleiben jedoch in den MCP-Toolargumenten enthalten und können in Backend-Fehlern auftauchen. ClickHouse 26.3.20.7 setzt Werte in den Abfragetext ein, und zwar in system.query_log, system.processes und system.text_log. Parameterbindung ist keine Datenschutzfunktion und verringert nicht die Anzahl der Vektorwerte, die in einem Toolaufruf gesendet werden.

Eine Abfrage vor der Ausführung prüfen

run_query führt auch DESCRIBE und EXPLAIN ESTIMATE aus. Beide Prüfungen sind optional: Verwenden Sie DESCRIBE, wenn Sie die Ausgabespalten und -typen einer Abfrage benötigen, und EXPLAIN ESTIMATE vor einem SELECT, das teuer werden könnte.

DESCRIBE (<query>) untersucht das Ergebnisschema und gibt dieselben Metadaten zu Ausgabespalten zurück wie DESCRIBE TABLE:

DESCRIBE (SELECT user, sum(amt) FROM events WHERE ts > now() - INTERVAL 30 DAY GROUP BY user)

user      String
sum(amt)  Decimal(38, 2)

ClickHouse muss die Abfrage analysieren, um die Antwort zu liefern. Daher werden Analysefehler hier mit ClickHouse-eigener Meldung angezeigt, statt erst mitten in der Ausführung:

DESCRIBE (SELECT usr FROM events)  -> Code: 47. Unknown expression identifier `usr` ... Maybe you meant: ['user']
DESCRIBE (SELECT * FROM nosuch)    -> Code: 60. Unknown table expression identifier 'nosuch'

Eine Abfrage, deren Beschreibung erfolgreich erstellt werden kann, kann bei der Ausführung dennoch aufgrund eines Speicherlimits oder eines Fehlers auf einem Remoteserver scheitern und sagt nichts über die Kosten aus.

EXPLAIN ESTIMATE <query> gibt die Teile, Zeilen und Markierungen zurück, die die Abfrage lesen würde, jeweils eine Zeile pro Tabelle. Damit lässt sich eine Primärschlüsselsuche von einem vollständigen Scan unterscheiden:

EXPLAIN ESTIMATE SELECT count() FROM events WHERE id = 42

database  table   parts  rows   marks
default   events  1      8192   1

Dabei handelt es sich um geschätzte Lesevorgänge aus Tabellen der MergeTree-Familie nach der Beschneidung anhand von Primärschlüssel und Partition. Sie geben weder die Laufzeit noch die Ergebnisgröße an; andere Tabellen-Engines werden nicht abgedeckt.

Keine der beiden Anweisungen führt den Abfragekörper aus, aber die Analyse ist nicht immer kostenlos: DESCRIBE (SELECT (SELECT sleep(1))) führt die skalare Unterabfrage während der Analyse aus. Beide sind schreibgeschützt und funktionieren unter dem standardmäßigen CLICKHOUSE_ALLOW_WRITE_ACCESS=false. Siehe die ClickHouse-Dokumentation zu EXPLAIN ESTIMATE und DESCRIBE.

chDB-Tools

  • run_chdb_select_query
    • SQL-Abfragen mit der eingebetteten ClickHouse-Engine von chDB ausführen.
    • Eingabe: query (string): Die auszuführende SQL-Abfrage.
    • Ganzzahlen außerhalb [-9007199254740991, 9007199254740991] werden als Dezimalzeichenfolgen zurückgegeben.
    • Abfragedaten direkt aus verschiedenen Quellen (Dateien, URLs, Datenbanken) ohne ETL-Prozesse abrufen.
    • Erfordert das optionale Extra chdb: pip install 'mcp-clickhouse[chdb]'

Health-Check-Endpunkt

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

  • Gibt 200 OK (Body: OK) zurück, wenn der Server gesund ist und eine Verbindung zu ClickHouse herstellen kann.
  • Gibt 503 Service Unavailable mit einer allgemeinen Fehlermeldung zurück, wenn der Server keine Verbindung zu ClickHouse herstellen kann.
  • Gibt 503 zurück, wenn eine ClickHouse-Prüfung nicht innerhalb von zwei Sekunden abgeschlossen wird. Gleichzeitige Anfragen verwenden dieselbe laufende Prüfung.
  • Verwendet ein abgeschlossenes Prüfergebnis eine Sekunde lang erneut, sodass schnell aufeinanderfolgende Prüfungen nicht jeweils eine Verbindung zu ClickHouse herstellen. Ein Fehler oder eine Wiederherstellung kann daher mit bis zu einer Sekunde Verzögerung gemeldet werden.

GET- und HEAD-Anfragen an den Endpunkt sind absichtlich nicht authentifiziert und von der Host- und Origin-Validierung ausgenommen, damit Orchestrator-Prüfungen (z. B. Kubernetes-Liveness-/Readiness-Prüfungen, Load Balancer) zur Laufzeit zugewiesene Pod- oder Ziel-IP-Adressen ohne zusätzliche Konfiguration verwenden können. /health ist reserviert und kann nicht als MCP-Transportpfad verwendet werden. Der Antworttext ist bewusst minimal gehalten, um Backend-Versionszeichenfolgen oder Fehlerdetails nicht offenzulegen; Fehler können zur Diagnose in den Serverprotokollen eingesehen werden.

Beispiel:

curl http://localhost:8000/health
# Response: OK

Sicherheit

Authentifizierung für HTTP-/SSE-Transporte

Bei Verwendung des HTTP- oder SSE-Transports ist die Authentifizierung standardmäßig erforderlich. Für den Transport stdio (Standard) ist keine Authentifizierung erforderlich, da er ausschließlich über die Standardeingabe und -ausgabe kommuniziert.

Es werden drei Authentifizierungsmodi unterstützt. Wählen Sie einen aus:

ModusVerwendungEnv-Variable
Statisches Bearer-TokenEinfache Bereitstellungen, interne DiensteCLICKHOUSE_MCP_AUTH_TOKEN
OAuth / OIDC (über FastMCP)Azure Entra, Google, GitHub, WorkOS usw.FASTMCP_SERVER_AUTH=<provider-class-path> (+ anbieterspezifische FASTMCP_SERVER_AUTH_*-Variablen)
DeaktiviertNur lokale EntwicklungCLICKHOUSE_MCP_AUTH_DISABLED=true

Der Start schlägt fehl, wenn für HTTP-/SSE-Transporte keine dieser Optionen konfiguriert ist.

Authentifizierung einrichten

  1. Generieren Sie ein sicheres Token (beliebige zufällige Zeichenfolge):

    # Using uuidgen (macOS/Linux)
uuidgen

# Using openssl
openssl rand -hex 32

  2. Konfigurieren Sie den Server mit dem Token:

    export CLICKHOUSE_MCP_AUTH_TOKEN="your-generated-token"

  3. Konfigurieren Sie Ihren MCP-Client so, dass er das Token in Anfragen mitsendet:

    Für Claude Desktop mit HTTP-/SSE-Transport:

    {
  "mcpServers": {
    "mcp-clickhouse": {
      "url": "http://127.0.0.1:8000",
      "headers": {
        "Authorization": "Bearer your-generated-token"
      }
    }
  }
}

    Hinweis: Der Endpunkt /health ist absichtlich nicht authentifiziert (siehe oben Health-Check-Endpunkt). Um zu überprüfen, ob die Bearer-Token-Authentifizierung nicht authentifizierte Anfragen tatsächlich ablehnt, rufen Sie den MCP-Endpunkt selbst auf, z. B. mit dem MCP Inspector oder indem Sie eine JSON-RPC-Anfrage mit und ohne den Header Authorization an /mcp senden und bestätigen, dass der nicht authentifizierte Aufruf 401 zurückgibt.

OAuth / OIDC über FastMCP

Delegieren Sie bei Produktionsbereitstellungen mit Identitätsanbietern (Azure Entra, Google, GitHub, WorkOS usw.) die Authentifizierung an die integrierten Authentifizierungsanbieter von FastMCP, statt ein statisches Token zu verwenden. Setzen Sie FASTMCP_SERVER_AUTH auf den vollständigen Klassenpfad eines FastMCP-Authentifizierungsanbieters, zusammen mit den anbieterspezifischen FASTMCP_SERVER_AUTH_*-Variablen, und lassen Sie CLICKHOUSE_MCP_AUTH_TOKEN ungesetzt.

Beispiel (Azure Entra):

export FASTMCP_SERVER_AUTH=fastmcp.server.auth.providers.azure.AzureProvider
export FASTMCP_SERVER_AUTH_AZURE_TENANT_ID="<tenant-id>"
export FASTMCP_SERVER_AUTH_AZURE_CLIENT_ID="<client-id>"
export FASTMCP_SERVER_AUTH_AZURE_CLIENT_SECRET="<client-secret>"
export FASTMCP_SERVER_AUTH_AZURE_BASE_URL="https://mcp.example.com"
export FASTMCP_SERVER_AUTH_AZURE_REQUIRED_SCOPES="read access_as_user"

mcp-clickhouse behält diese FastMCP-2.14.7-Umgebungspräfixe für die integrierten Anbieter von FastMCP 4.0.0 bei:

Klassenpfad des AnbietersVariablenpräfix des Anbieters
fastmcp.server.auth.providers.auth0.Auth0ProviderFASTMCP_SERVER_AUTH_AUTH0_
fastmcp.server.auth.providers.aws.AWSCognitoProviderFASTMCP_SERVER_AUTH_AWS_COGNITO_
fastmcp.server.auth.providers.azure.AzureProviderFASTMCP_SERVER_AUTH_AZURE_
fastmcp.server.auth.providers.descope.DescopeProviderFASTMCP_SERVER_AUTH_DESCOPEPROVIDER_
fastmcp.server.auth.providers.discord.DiscordProviderFASTMCP_SERVER_AUTH_DISCORD_
fastmcp.server.auth.providers.github.GitHubProviderFASTMCP_SERVER_AUTH_GITHUB_
fastmcp.server.auth.providers.google.GoogleProviderFASTMCP_SERVER_AUTH_GOOGLE_
fastmcp.server.auth.providers.introspection.IntrospectionTokenVerifierFASTMCP_SERVER_AUTH_INTROSPECTION_
fastmcp.server.auth.providers.jwt.JWTVerifierFASTMCP_SERVER_AUTH_JWT_
fastmcp.server.auth.providers.oci.OCIProviderFASTMCP_SERVER_AUTH_OCI_
fastmcp.server.auth.providers.scalekit.ScalekitProviderFASTMCP_SERVER_AUTH_SCALEKITPROVIDER_
fastmcp.server.auth.providers.supabase.SupabaseProviderFASTMCP_SERVER_AUTH_SUPABASE_
fastmcp.server.auth.providers.workos.WorkOSProviderFASTMCP_SERVER_AUTH_WORKOS_
fastmcp.server.auth.providers.workos.AuthKitProviderFASTMCP_SERVER_AUTH_AUTHKITPROVIDER_

Hängen Sie den großgeschriebenen Feldnamen des Anbieters an das Präfix an. Die Konfigurationsanforderungen der einzelnen Anbieter finden Sie in der FastMCP-Dokumentation.

Direkt in der Prozessumgebung gesetzte Authentifizierungswerte haben unabhängig von der Groß- und Kleinschreibung Vorrang. Der standardmäßige Ladevorgang von .env beginnt im installierten Paketverzeichnis von mcp_clickhouse, löst zuerst Symlinks auf und geht dann bis zum Dateisystemstamm nach oben. Er lädt die erste gefundene .env und lädt nichts, wenn keine vorhanden ist. Das Arbeitsverzeichnis wird nie gelesen, unabhängig davon, wie der Server gestartet wird. Bei einem ausgecheckten Quellcode-Repository wird normalerweise die Repository-Stammdatei .env gefunden. Diese Datei kann auch FASTMCP_SERVER_AUTH und dessen Provider-Felder bereitstellen. Deren Werte haben Vorrang vor der expliziten Authentifizierungsdatei oder der Kompatibilitätsdatei. Für die Kompatibilität mit FastMCP 2 liest mcp-clickhouse fehlende Provider-Felder aus .env im Arbeitsverzeichnis. Dieser Kompatibilitäts-Fallback kann jedoch nicht FASTMCP_SERVER_AUTH auswählen. Ein in der Prozessumgebung gesetztes FASTMCP_ENV_FILE ersetzt diesen Kompatibilitäts-Fallback und kann sowohl den Selektor als auch Provider-Felder bereitstellen. Setzen Sie es vor dem Start. Der Kompatibilitätslader von mcp-clickhouse liest aus dieser Datei nur FASTMCP_SERVER_AUTH und FASTMCP_SERVER_AUTH_*, sodass damit keine CLICKHOUSE_*-Einstellungen eingeschleust werden können. FastMCP 4 kann dieselbe Datei für seine umfassenderen Einstellungen verwenden. Ein benutzerdefinierter Provider erhält keine aus der Umgebung abgeleiteten Konstruktorargumente und muss ohne Argumente instanziiert werden können.

Betrachten Sie sowohl gefundene .env-Dateien als auch Dateien im Arbeitsverzeichnis als vertrauenswürdige Authentifizierungskonfiguration. Jede Person, die in einem Verzeichnis vom Paketverzeichnis bis zum Dateisystemstamm eine .env erstellen oder beschreiben kann, kann steuern, welche Datei gefunden wird, den Provider auswählen und dessen Felder festlegen. Jede Person, die die Datei im Arbeitsverzeichnis beschreiben kann, kontrolliert alle Provider-Felder, die weder in der Prozessumgebung noch in der gefundenen Konfiguration gesetzt sind, einschließlich Signaturschlüsseln, Ausstellern und Endpunkten sowie Client-Geheimnissen. Ein in der Prozessumgebung gesetztes FASTMCP_ENV_FILE, das auf eine Datei im Besitz des Betreibers verweist, deaktiviert den Fallback auf das Arbeitsverzeichnis.

FastMCP 4 hat den Standardspeicher für OAuth-Proxy-Clients geändert. Bei Bereitstellungen, die auf dem Standardspeicher des OAuth-Proxys von FastMCP 2 beruhten, müssen Clients sich erneut registrieren und autorisieren. Kompatibler benutzerdefinierter Speicher, statische Bearer-Tokens und die JWT-Verifizierung sind davon nicht betroffen.

Entwicklungsmodus (Authentifizierung deaktivieren)

Für lokale Entwicklung und Tests können Sie die Authentifizierung deaktivieren, indem Sie Folgendes festlegen:

export CLICKHOUSE_MCP_AUTH_DISABLED=true
export CLICKHOUSE_MCP_ALLOWED_HOSTS=127.0.0.1:8000,localhost:8000

WARNUNG: Verwenden Sie dies nur für die lokale Entwicklung. Deaktivieren Sie die Authentifizierung nicht, wenn der Server über ein Netzwerk erreichbar ist.

Konfiguration

Dieser MCP-Server unterstützt sowohl ClickHouse als auch chDB. Je nach Bedarf können Sie eines oder beide aktivieren. Python 3.10 bis 3.15 werden unterstützt. Für lokale Starts wird Python 3.12 empfohlen. chDB unterstützt Python 3.10 bis 3.14. Unter Python 3.15 überspringt das Extra chdb die Installation von chDB mithilfe eines Abhängigkeitsmarkers. Bei Python-3.15-Installationen werden derzeit lz4 und PyYAML aus dem Quellcode erstellt, unabhängig davon, ob das Extra chdb verwendet wird. Für lz4 ist ein C-Compiler erforderlich.

  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 Folgendes hinzu:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.12",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_PORT": "<clickhouse-port>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_ROLE": "<clickhouse-role>",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30"
      }
    }
  }
}

Aktualisieren Sie die Umgebungsvariablen so, dass sie auf Ihren eigenen ClickHouse-Dienst verweisen.

Wenn Sie es stattdessen mit dem ClickHouse SQL Playground ausprobieren möchten, können Sie die folgende Konfiguration verwenden:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.12",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
        "CLICKHOUSE_PORT": "8443",
        "CLICKHOUSE_USER": "demo",
        "CLICKHOUSE_PASSWORD": "",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30"
      }
    }
  }
}

Fügen Sie für chDB (die eingebettete ClickHouse-Engine) die folgende Konfiguration hinzu:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse[chdb]",
        "--python",
        "3.12",
        "mcp-clickhouse"
      ],
      "env": {
        "CHDB_ENABLED": "true",
        "CLICKHOUSE_ENABLED": "false",
        "CHDB_DATA_PATH": "/path/to/chdb/data"
      }
    }
  }
}

Sie können ClickHouse und chDB auch gleichzeitig aktivieren:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse[chdb]",
        "--python",
        "3.12",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_PORT": "<clickhouse-port>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30",
        "CHDB_ENABLED": "true",
        "CHDB_DATA_PATH": "/path/to/chdb/data"
      }
    }
  }
}

  1. Suchen Sie den Befehlseintrag für uv und ersetzen Sie ihn durch den absoluten Pfad zur ausführbaren Datei uv. Dadurch wird sichergestellt, dass beim Starten des Servers die richtige Version von uv verwendet wird. Auf einem Mac können Sie diesen Pfad mit which uv ermitteln.

  2. Starten Sie Claude Desktop neu, damit die Änderungen übernommen werden.

Optionaler Schreibzugriff

Standardmäßig erzwingt dieser MCP schreibgeschützte Abfragen, damit bei der Erkundung keine versehentlichen Änderungen vorgenommen werden. Um DDL- oder INSERT-Anweisungen zuzulassen, setzen Sie die Umgebungsvariable CLICKHOUSE_ALLOW_WRITE_ACCESS auf true. Der Server erzwingt weiterhin den schreibgeschützten Modus, wenn die ClickHouse-Instanz selbst Schreibvorgänge nicht zulässt.

Im schreibgeschützten Modus darf der ClickHouse-Benutzer weiterhin eigene Abfragen abbrechen, einschließlich Abfragen anderer Verbindungen, die denselben Benutzer verwenden. Verwenden Sie auch im schreibgeschützten Modus einen dedizierten ClickHouse-Benutzer. Verwenden Sie für Workloads, die sich nicht gegenseitig abbrechen dürfen, separate ClickHouse-Benutzer.

Schutz vor destruktiven Vorgängen

Auch wenn der Schreibzugriff aktiviert ist (CLICKHOUSE_ALLOW_WRITE_ACCESS=true), erfordern destruktive Vorgänge aus Sicherheitsgründen eine zusätzliche ausdrückliche Freigabe. Die Prüfung umfasst jede DROP-Anweisung (einschließlich der Klauseln ALTER TABLE ... DROP PARTITION / DROP PART / DROP COLUMN), alle TRUNCATE, DELETE und UPDATE (sowohl die leichtgewichtigen Anweisungen als auch die Mutationen ALTER TABLE ... DELETE / ALTER TABLE ... UPDATE), REPLACE TABLE, CREATE OR REPLACE, ALTER TABLE ... REPLACE PARTITION, ALTER TABLE ... CLEAR COLUMN / CLEAR INDEX / CLEAR PROJECTION sowie DETACH ... PERMANENTLY. Schlüsselwörter in Zeichenfolgenliteralen, in Anführungszeichen gesetzten Bezeichnern, SQL-Kommentaren und Parameternamen von {name:Type} werden ignoriert. Sie lösen die Prüfung also weder aus noch können sie eine Anweisung vor der Prüfung verbergen.

Diese Prüfung wird im MCP-Server ausgeführt und bietet einen bestmöglichen Schutz vor Versehen. Sie ist keine Sicherheitsgrenze. Die Sicherheitsgrenze bilden die Berechtigungen des ClickHouse-Benutzers. Der schreibgeschützte Modus (Standard) wird serverseitig über readonly=1 erzwungen. Die Sperre für destruktive Vorgänge wird nicht serverseitig erzwungen.

Verwenden Sie im Schreibmodus für den MCP-Server einen dedizierten ClickHouse-Benutzer mit ausschließlich den benötigten Berechtigungen:

CREATE USER mcp_agent IDENTIFIED BY '...';
GRANT SELECT, INSERT, CREATE TABLE, ALTER ADD COLUMN ON mydb.* TO mcp_agent;

Datenändernde Vorgänge, für die Berechtigungen außerhalb dieser Zuweisungen erforderlich sind, schlagen serverseitig mit ACCESS_DENIED fehl, unabhängig von den MCP-Flags. Die Servereinstellungen max_table_size_to_drop und max_partition_size_to_drop können den möglichen Schadensumfang ebenfalls begrenzen, wenn sie durch Einstellungseinschränkungen festgelegt werden.

Um destruktive Vorgänge zu aktivieren, setzen Sie beide Flags:

"env": {
  "CLICKHOUSE_ALLOW_WRITE_ACCESS": "true",
  "CLICKHOUSE_ALLOW_DROP": "true"
}

Dieser zweistufige Ansatz erschwert versehentliches Löschen:

  • Schreibvorgänge (INSERT, CREATE, ALTER ADD COLUMN) erfordern CLICKHOUSE_ALLOW_WRITE_ACCESS=true
  • Destruktive Vorgänge (DROP, TRUNCATE, DELETE, UPDATE und die übrigen oben aufgeführten Vorgänge) erfordern zusätzlich CLICKHOUSE_ALLOW_DROP=true

Ausführung ohne uv (mit System-Python)

Wenn Sie statt uv die System-Python-Installation verwenden möchten, können Sie das Paket von PyPI installieren und direkt ausführen:

  1. Installieren Sie das Paket mit pip:

    python3 -m pip install mcp-clickhouse

    Um auch chDB-Unterstützung zu installieren:

    python3 -m pip install 'mcp-clickhouse[chdb]'

    So aktualisieren Sie auf die neueste Version:

    python3 -m pip install --upgrade mcp-clickhouse

  2. Aktualisieren Sie die Claude-Desktop-Konfiguration, damit Python direkt verwendet wird:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "python3",
      "args": [
        "-m",
        "mcp_clickhouse.main"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_PORT": "<clickhouse-port>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30"
      }
    }
  }
}

Alternativ können Sie das installierte Skript direkt verwenden:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "mcp-clickhouse",
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_PORT": "<clickhouse-port>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30"
      }
    }
  }
}

Hinweis: Verwenden Sie den vollständigen Pfad zur ausführbaren Python-Datei oder zum Skript mcp-clickhouse, wenn diese nicht in Ihrem System-PATH enthalten sind. Die Pfade können Sie mit folgenden Befehlen ermitteln:

  • which python3 für die ausführbare Python-Datei
  • which mcp-clickhouse für das installierte Skript

Benutzerdefinierte Middleware

Sie können dem MCP-Server benutzerdefinierte Middleware hinzufügen, ohne den Quellcode zu ändern. FastMCP bietet ein Middleware-System, mit dem Sie MCP-Protokollnachrichten (Tool-Aufrufe, Ressourcenlesevorgänge, Prompts usw.) abfangen und verarbeiten können.

Verwendung

  1. Erstellen Sie ein Python-Modul mit Middleware-Klassen, die Middleware erweitern, sowie einer Funktion setup_middleware(mcp):
# my_middleware.py
import logging
from fastmcp.server.middleware import Middleware, MiddlewareContext, CallNext

logger = logging.getLogger("my-middleware")

class LoggingMiddleware(Middleware):
    """Log all tool calls."""
    
    async def on_call_tool(self, context: MiddlewareContext, call_next: CallNext):
        tool_name = context.message.name if hasattr(context.message, 'name') else 'unknown'
        logger.info(f"Calling tool: {tool_name}")
        result = await call_next(context)
        logger.info(f"Tool {tool_name} completed")
        return result

def setup_middleware(mcp):
    """Register middleware with the MCP server."""
    mcp.add_middleware(LoggingMiddleware())
  1. Setzen Sie die Umgebungsvariable MCP_MIDDLEWARE_MODULE auf den Modulnamen (ohne die Erweiterung .py):
{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": ["run", "--with", "mcp-clickhouse", "--python", "3.12", "mcp-clickhouse"],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "MCP_MIDDLEWARE_MODULE": "my_middleware"
      }
    }
  }
}
  1. Stellen Sie sicher, dass sich Ihr Middleware-Modul im Python-Importpfad befindet (z. B. im selben Verzeichnis, in dem der MCP-Server ausgeführt wird, oder als Paket installiert).

Beispiel-Middleware

Ein Beispielmodul für Middleware mit gängigen Mustern befindet sich in example_middleware.py:

  • Protokollierung aller MCP-Anfragen
  • Gezielte Protokollierung von Tool-Aufrufen
  • Messung der Verarbeitungszeit von Anfragen

So verwenden Sie das Beispiel:

"env": {
  "MCP_MIDDLEWARE_MODULE": "example_middleware"
}

Middleware-Funktionen

Die Basisklasse Middleware stellt Hooks für verschiedene MCP-Vorgänge bereit:

  • on_message(context, call_next) – Wird für alle Nachrichten aufgerufen
  • on_request(context, call_next) – Wird für alle Anfragen aufgerufen
  • on_notification(context, call_next) – Wird für alle Benachrichtigungen aufgerufen
  • on_call_tool(context, call_next) – Wird bei der Ausführung eines Tools aufgerufen
  • on_read_resource(context, call_next) – Wird beim Lesen einer Ressource aufgerufen
  • on_get_prompt(context, call_next) – Wird beim Abrufen eines Prompts aufgerufen
  • on_list_tools(context, call_next) – Wird beim Auflisten von Tools aufgerufen
  • on_list_resources(context, call_next) – Wird beim Auflisten von Ressourcen aufgerufen
  • on_list_resource_templates(context, call_next) – Wird beim Auflisten von Ressourcenvorlagen aufgerufen
  • on_list_prompts(context, call_next) – Wird beim Auflisten von Prompts aufgerufen

Jeder Hook erhält ein MiddlewareContext-Objekt mit der Nachricht und Metadaten sowie eine Funktion call_next, mit der die Verarbeitungskette fortgesetzt wird.

Dynamische Client-Konfiguration über den Context-Zustand

Middleware kann die ClickHouse-Clientkonfiguration pro Anfrage mithilfe des Context-Zustandsschlüssels CLIENT_CONFIG_OVERRIDES_KEY überschreiben. Der Server führt diese Überschreibungen mit der Basiskonfiguration aus den Umgebungsvariablen zusammen.

from fastmcp.server.dependencies import get_context
from fastmcp.server.middleware import CallNext, Middleware, MiddlewareContext
from mcp_clickhouse.mcp_server import CLIENT_CONFIG_OVERRIDES_KEY


class ClientConfigMiddleware(Middleware):
    async def on_call_tool(self, context: MiddlewareContext, call_next: CallNext):
        ctx = get_context()
        await ctx.set_state(
            CLIENT_CONFIG_OVERRIDES_KEY,
            {
                "connect_timeout": 60,
                "send_receive_timeout": 120,
            },
            serializable=False,
        )
        return await call_next(context)

Damit lassen sich fortgeschrittene Anwendungsfälle umsetzen, etwa dynamische Anpassungen von Timeouts, mandantenspezifisches Routing oder benutzerspezifische Verbindungseinstellungen.

Der Zustandswert muss ein Dictionary sein. Verschachtelte Werte für settings und generic_args müssen Mappings sein und werden mit der Basiskonfiguration zusammengeführt. Ungültige Werte führen zum Fehlschlagen des Tool-Aufrufs, bevor ein ClickHouse-Client erstellt wird. CLICKHOUSE_ROLE bleibt aktiv, sofern die Überschreibung nicht ausdrücklich settings.role angibt. Schlüssel der obersten Ebene role und ch_role sowie dieselben Schlüssel unter generic_args werden abgelehnt.

Legen Sie verify, ca_cert, client_cert, client_cert_key, tls_mode, server_host_name und pool_mgr nur als Überschreibungen der obersten Ebene fest. Sie dürfen nicht unter generic_args verschachtelt werden. Ein benutzerdefiniertes pool_mgr kann nicht mit verwalteten CA- oder Client-Zertifikatseinstellungen kombiniert werden. DSN-Abfrageparameter können diese Schlüssel nicht festlegen, und ein DSN kann nicht das chdb-Backend auswählen. Verwenden Sie explizite Überschreibungen der obersten Ebene für host, port, username, password, database und secure, um die Verbindung zu ändern. Ein weitergeleiteter DSN ersetzt weder bereits gesetzte Basisverbindungsfelder noch wählt er TLS aus. Er kann leere Felder ausfüllen und unterstützte Abfrageparameter wie query_limit bereitstellen. Überschreibungen für secure und verify akzeptieren boolesche Werte oder die Zeichenfolgen true und false. verify akzeptiert außerdem proxy, das sich wie tls_mode: proxy verhält, wenn tls_mode nicht gesetzt ist, und daher die Basic-Authentifizierung mit dem Umgebungspasswort verwendet. Eine Überschreibung von secure wählt die passende Schnittstelle https oder http aus und ändert den Port nicht. Eine explizite Überschreibung von interface muss http oder https sein und mit secure übereinstimmen. Nach dem Zusammenführen der Überschreibungen lassen die Standardmodi und der Modus mutual das Passwort weg. Die Modi proxy und strict verwenden die Basic-Authentifizierung mit dem Umgebungspasswort, sofern die Überschreibung keine eigenen Anmeldedaten bereitstellt.

Behandeln Sie diese Überschreibungen als vertrauenswürdige Middleware-Eingaben. Middleware muss aus Anfragen abgeleitete Werte authentifizieren und autorisieren, bevor sie diese festlegt. Verwenden Sie serializable=False, damit FastMCP den Wert im anfragebezogenen Zustand speichert. Der standardmäßige serializable=True speichert den Sitzungszustand und wird vom Server abgelehnt. Der Server erstellt eine Momentaufnahme des Werts, bevor blockierende Datenbankarbeit gestartet wird. Speichern Sie keine Mandantendaten im sitzungsbezogenen Context-Zustand. Eine abgelehnte sitzungsbezogene Überschreibung bleibt an einer älteren MCP-Sitzung hängen und führt dazu, dass spätere Tool-Aufrufe in dieser Sitzung fehlschlagen, bis der Client die Verbindung erneut herstellt. Eine ClickHouse-Rolle pro Anfrage ist Verbindungskonfiguration und keine Grenze für die Mandantenautorisierung. Erzwingen Sie die Mandantenisolierung mit ClickHouse-Benutzern, Rollen und Berechtigungen.

Entwicklung

  1. Führen Sie im Verzeichnis test-services den Befehl docker compose up -d aus, um den ClickHouse-Cluster zu starten.
  2. Fügen Sie die folgenden Variablen zu einer Datei .env im Stammverzeichnis des Repositorys hinzu.

Hinweis: Die Verwendung des Benutzers default in diesem Kontext ist ausschließlich für die lokale Entwicklung vorgesehen.

CLICKHOUSE_HOST=localhost
CLICKHOUSE_PORT=8123
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse

  1. Führen Sie uv sync --locked --extra dev aus, um die Abhängigkeiten zu installieren. Fügen Sie unter Python 3.10 bis 3.14 --extra chdb für die chDB-Entwicklung hinzu. Befolgen Sie zum Installieren von uv die Anweisungen hier. Führen Sie anschließend source .venv/bin/activate aus.

  2. Führen Sie für einfache Tests mit dem MCP Inspector uv run fastmcp dev inspector mcp_clickhouse/mcp_server.py:mcp aus, um den MCP-Server zu starten.

  3. So testen Sie den HTTP-Transport und den Health-Check-Endpunkt:

    # For development, disable authentication
CLICKHOUSE_MCP_SERVER_TRANSPORT=http CLICKHOUSE_MCP_AUTH_DISABLED=true CLICKHOUSE_MCP_ALLOWED_HOSTS=127.0.0.1:8000,localhost:8000 python -m mcp_clickhouse.main

# Or with authentication (generate a token first)
CLICKHOUSE_MCP_SERVER_TRANSPORT=http CLICKHOUSE_MCP_AUTH_TOKEN="your-token" python -m mcp_clickhouse.main

# Then in another terminal:
curl http://localhost:8000/health

Code-Layout

Das Paket verwendet ein flaches Modul-Layout. Beginnen Sie mit mcp_server.py für die Serverzusammenstellung und Registrierung und verfolgen Sie anschließend die Implementierung bis zu ihrem zuständigen Modul.

ModulZuständigkeit
mcp_server.py, main.pyZusammenstellung beim Start, Registrierung von Tools und Prompts, Koordination des Herunterfahrens und CLI-Start
clients.pyAnfragekonfiguration, zwischengespeicherte ClickHouse-Verbindungen und Client-Leases
queries.pyAbfrageausführung, Abbruch und Schutz vor destruktiven Vorgängen
metadata.pyErmittlung von Datenbanken und Tabellen, Metadatenmodelle und Paginierung
chdb_backend.py, chdb_prompt.pyOptionale chDB-Initialisierung, Abfrageausführung und Prompt-Inhalt
health.py, executors.pyHealth-Prüfungen und Caching sowie die Worker-Pools für Servervorgänge
auth.py, transport.py, http_security.pyLaden von Dotenv-Dateien, Authentifizierung, Erstellung der HTTP/SSE-App und Host-/Origin-Validierung
mcp_env.py, serialization.pyUmgebungskonfiguration und JSON-Ergebnisserialisierung
mcp_middleware_hook.py, skills_advisor.pyLaden benutzerdefinierter Middleware und Serveranweisungen

Jede Serverzusammenstellung verwaltet ihre eigenen Worker-Pools, ihren Client-Cache, aktive Abfragen, ihren Paginierungs-Cache, ihren Health-Status und ihr chDB-Backend. Worker- und Client-Bereinigung erfolgt beim Prozessende. Paketimporte initialisieren den Standardserver, auch beim erstmaligen Import eines extrahierten Moduls.

Patchen Sie in Tests das Modul oder die Besitzerinstanz, an der der Code eine Abhängigkeit ausliest. Patchen Sie beispielsweise mcp_clickhouse.clients.clickhouse_connect.get_client für die Client-Erstellung. Kompatibilitätsimporte in mcp_server.py können separate Bindungen von denen sein, die eine Implementierung verwendet.

Umgebungsvariablen

Die Konfiguration ist in unabhängige Gruppen unterteilt. Eine Verwechslung dieser Gruppen ist eine häufige Ursache für schwer zu diagnostizierende Verbindungsfehler:

GruppeVariablenSteuert
ClickHouse-DatenbankverbindungCLICKHOUSE_HOST, CLICKHOUSE_PORT, CLICKHOUSE_SECURE, CLICKHOUSE_VERIFY, ZertifikatsvariablenWie dieser MCP-Server über die HTTP-Schnittstelle eine Verbindung zu Ihrem ClickHouse-Cluster herstellt
MCP-Server / TransportCLICKHOUSE_MCP_*, FASTMCP_SERVER_AUTH, FASTMCP_SERVER_AUTH_*, FASTMCP_ENV_FILEMCP-Transport, Authentifizierung und Ausführungslimits für Abfrage-Tools
Middleware / chDBMCP_MIDDLEWARE_MODULE, CHDB_*Optionale Erweiterungen

[!IMPORTANT] CLICKHOUSE_SECURE, CLICKHOUSE_VERIFY, CLICKHOUSE_CA_CERT, CLICKHOUSE_CLIENT_CERT, CLICKHOUSE_CLIENT_CERT_KEY, CLICKHOUSE_TLS_MODE und CLICKHOUSE_PORT gelten ausschließlich für die ausgehende ClickHouse-Datenbankverbindung. Sie konfigurieren weder TLS, Client-Zertifikate, Ports noch die Authentifizierung für den eingehenden MCP-HTTP/SSE-Endpunkt.

Beispiel: Wenn der MCP-Server in Kubernetes hinter einem Ingress ausgeführt wird, der TLS terminiert, betrifft das den MCP-Transport. Richten Sie CLICKHOUSE_SECURE danach aus, wie der Pod ClickHouse selbst erreicht (HTTPS → true, einfaches HTTP → false). Wenn Sie CLICKHOUSE_SECURE=false setzen, weil sich der MCP-Server hinter einem Ingress befindet, verbindet sich der Server über HTTP mit ClickHouse – häufig mit einem ausschließlich für HTTPS vorgesehenen Port – und verursacht undurchsichtige HTTP-/TLS-Fehler in den Serverprotokollen.

ClickHouse-Datenbankverbindung

Diese Variablen konfigurieren den HTTP-Client clickhouse-connect und das Verhalten ClickHouse-gestützter Tools wie run_query, list_databases und list_tables. mcp-clickhouse erfordert clickhouse-connect 1.x, beginnend mit Version 1.0.0.

Erforderliche Variablen
  • CLICKHOUSE_HOST: Der Hostname Ihres ClickHouse-Servers (Datenbankendpunkt, nicht die Bind-Adresse des MCP-Servers)
  • CLICKHOUSE_USER: Der Benutzername für die ClickHouse-Authentifizierung
  • CLICKHOUSE_PASSWORD: Das Passwort für die ClickHouse-Authentifizierung
    • Erforderlich, sofern CLICKHOUSE_CLIENT_CERT nicht den Standard- oder den TLS-Modus "mutual" verwendet
    • Im Standardmodus oder im Modus "mutual" wird die Zertifikatsauthentifizierung verwendet und das Passwort nicht gesendet

[!CAUTION] Behandeln Sie Ihren MCP-Datenbankbenutzer wie jeden externen Client, der eine Verbindung zu Ihrer Datenbank herstellt, und gewähren Sie ihm nur die für den Betrieb erforderlichen Mindestberechtigungen. Die Verwendung von Standard- oder Administrationsbenutzern sollte jederzeit unbedingt vermieden werden.

Optionale Variablen
  • CLICKHOUSE_PORT: HTTP-Schnittstellenport Ihres ClickHouse-Servers
    • Standard: 8443, wenn CLICKHOUSE_SECURE=true, 8123, wenn CLICKHOUSE_SECURE=false
    • Muss normalerweise nicht festgelegt werden, außer bei Verwendung eines nicht standardmäßigen Ports
    • Muss ein HTTP-Schnittstellenport sein, nicht der native TCP-Protokollport, der von clickhouse-client verwendet wird
    • Häufige Werte:
      • HTTP: 8123 (unverschlüsselt) / 8443 (TLS) — wird von diesem Server und ClickHouse Cloud HTTPS verwendet
      • Native TCP-Verbindung (hier nicht unterstützt): 9000 (unverschlüsselt) / 9440 (TLS) — wird von clickhouse-client verwendet
    • Wenn der Server mit Port 9000 is for clickhouse-client program antwortet, sind Sie mit dem nativen Protokoll verbunden. Wechseln Sie zum HTTP-Port (8123/8443 oder zur HTTP-Portzuordnung Ihrer Bereitstellung)
  • CLICKHOUSE_ROLE: Die für die Authentifizierung zu verwendende ClickHouse-Rolle
    • Standard: Keine
    • Legen Sie diesen Wert fest, wenn Ihr Benutzer eine bestimmte Rolle benötigt
  • CLICKHOUSE_SECURE: HTTPS für die ClickHouse-Datenbankverbindung aktivieren (nicht für MCP-Clients)
    • Standard: "true"
    • Nur dann auf "false" setzen, wenn der MCP-Server ClickHouse über unverschlüsseltes HTTP erreicht (typisch für lokales Docker Compose auf Port 8123)
    • Für ClickHouse Cloud und jeden HTTPS-Datenbankendpunkt auf "true" belassen – auch wenn der MCP-Server selbst über HTTP, stdio oder einen Ingress bereitgestellt wird, der TLS separat beendet
    • Eine Nichtübereinstimmung dieses Flags mit dem Datenbankport (z. B. CLICKHOUSE_SECURE=false für Port 8443) ist ein häufiger Konfigurationsfehler und äußert sich meist in verwirrenden HTTP-Clientfehlern statt in einer eindeutigen Meldung wie „falsches Schema“
  • CLICKHOUSE_VERIFY: SSL-Zertifikatsüberprüfung für die HTTPS-Verbindung zu ClickHouse aktivieren/deaktivieren
    • Standard: "true"
    • Auf "false" setzen, um die Zertifikatsüberprüfung zu deaktivieren (für den Produktionseinsatz nicht empfohlen)
    • TLS-Zertifikate: Das Paket verwendet beim Start den Vertrauensspeicher Ihres Betriebssystems über truststore.inject_into_ssl(). Wenn die Einbindung mit MCP_CLICKHOUSE_TRUSTSTORE_DISABLE=1 deaktiviert ist oder fehlschlägt, wird die standardmäßige SSL-Verarbeitung von Python verwendet.
  • MCP_CLICKHOUSE_TRUSTSTORE_DISABLE: Betriebssystemweiten Vertrauensspeicher für TLS deaktivieren
    • Standard: nicht gesetzt (die Einbindung des Vertrauensspeichers ist aktiviert)
    • Vor dem Start exakt auf "1" setzen, um truststore.inject_into_ssl() zu überspringen und die standardmäßige SSL-Zertifikatsverarbeitung von Python zu verwenden. Andere Werte deaktivieren die Einbindung nicht.
    • Dadurch wird die Zertifikatsüberprüfung nicht deaktiviert. CLICKHOUSE_VERIFY steuert weiterhin die Überprüfung für die HTTPS-Verbindung zu ClickHouse.
  • CLICKHOUSE_CA_CERT: Pfad zu einem PEM-CA-Zertifikatsbündel für die HTTPS-Verbindung zu ClickHouse
    • Standard: Keine (verwendet den Vertrauensspeicher des Betriebssystems, sofern dessen Einbindung nicht deaktiviert ist oder fehlschlägt)
    • Verwenden Sie diese Option allein, wenn ein ClickHouse-Server oder ein privater Proxy ein von einer privaten CA signiertes Zertifikat vorlegt. Dadurch wird die Überprüfung des Serverzertifikats geändert, aber keine Client-Zertifikatsauthentifizierung aktiviert.
    • Erfordert CLICKHOUSE_SECURE=true und CLICKHOUSE_VERIFY=true
  • CLICKHOUSE_CLIENT_CERT: Pfad zu einem PEM-Clientzertifikat für die HTTPS-Verbindung zu ClickHouse
    • Standard: Keine
    • Die Datei kann auch den privaten Schlüssel enthalten. Andernfalls legen Sie CLICKHOUSE_CLIENT_CERT_KEY fest.
    • Der ClickHouse-Benutzer wird weiterhin über CLICKHOUSE_USER festgelegt.
  • CLICKHOUSE_CLIENT_CERT_KEY: Pfad zum privaten PEM-Schlüssel für CLICKHOUSE_CLIENT_CERT
    • Standard: Keine
    • Optional, wenn der private Schlüssel in der Clientzertifikatsdatei enthalten ist
    • Kann nicht ohne CLICKHOUSE_CLIENT_CERT verwendet werden
  • CLICKHOUSE_TLS_MODE: Verwendung von CLICKHOUSE_CLIENT_CERT durch clickhouse-connect
    • Standard: Keine; bei festgelegtem Clientzertifikat entspricht dies "mutual"
    • "mutual": Das Clientzertifikat für die X.509-Benutzerauthentifizierung bei ClickHouse verwenden. CLICKHOUSE_PASSWORD ist optional und wird nicht gesendet.
    • "proxy": Das Clientzertifikat einem TLS-beendenden Proxy vorlegen und anschließend die ClickHouse-Basisauthentifizierung verwenden. CLICKHOUSE_PASSWORD ist erforderlich.
    • "strict": Das Clientzertifikat vorlegen, weil der ClickHouse-Server es auf TLS-Ebene verlangt, und anschließend die ClickHouse-Basisauthentifizierung verwenden. CLICKHOUSE_PASSWORD ist erforderlich. Dieser Modus verbessert die Überprüfung des Serverzertifikats nicht. CLICKHOUSE_VERIFY steuert diese Überprüfung.
    • clickhouse-connect behandelt "proxy" und "strict" identisch. Die beiden Namen dokumentieren die Absicht.
    • Werte werden von Leerzeichen am Anfang und Ende bereinigt und ohne Beachtung der Groß-/Kleinschreibung ausgewertet. Ein leerer Wert gilt als nicht gesetzt. Andere Werte werden abgewiesen, bevor ein ClickHouse-Client erstellt wird, und zwar beim ersten Aufruf eines ClickHouse-Tools oder bei der /health-Prüfung.
    • Erfordert CLICKHOUSE_CLIENT_CERT. Für alle Clientzertifikatoptionen ist CLICKHOUSE_SECURE=true erforderlich.
  • CLICKHOUSE_SERVER_HOST_NAME: Serverhostname für die SNI-Überschreibung und Zertifikatsvalidierung bei der ClickHouse-Verbindung
    • Standard: Keine (verwendet den Verbindungshostnamen)
    • Dies ist nützlich, wenn Sie über Proxys oder Load Balancer eine Verbindung herstellen, bei denen sich der Zertifikatshostname vom Verbindungshostnamen unterscheidet. Wenn dieser Wert festgelegt ist, wird der Hostname sowohl für SNI (Server Name Indication) während des TLS-Handshakes als auch für die Validierung des Zertifikatshostnamens verwendet.
  • CLICKHOUSE_PROXY_PATH: URL-Pfadpräfix für den ClickHouse-HTTP-Endpunkt
    • Standard: Keine
    • Legen Sie diesen Wert fest, wenn die ClickHouse-HTTP-Schnittstelle hinter einem Reverse-Proxy unter einem Pfadpräfix bereitgestellt wird (z. B. /clickhouse)
  • CLICKHOUSE_CONNECT_TIMEOUT: Verbindungs-Timeout in Sekunden für den ClickHouse-Client
    • Standard: "30"
    • Erhöhen Sie diesen Wert, wenn Verbindungs-Timeouts auftreten
  • CLICKHOUSE_SEND_RECEIVE_TIMEOUT: Sende-/Empfangs-Timeout in Sekunden für den ClickHouse-Client
    • Standard: der kleinere Wert von 300 und CLICKHOUSE_MCP_QUERY_TIMEOUT + 5, damit Worker-Threads kurz nach einem Query-Timeout wieder freigegeben werden
    • Bei expliziter Festlegung wird der Wert unverändert verwendet (z. B. "300" für lang laufende Abfragen)
  • CLICKHOUSE_DATABASE: Zu verwendende Standard-ClickHouse-Datenbank
    • Standard: Keine (verwendet den Serverstandard)
    • Legen Sie diesen Wert fest, um automatisch eine Verbindung zu einer bestimmten Datenbank herzustellen
  • CLICKHOUSE_ENABLED: ClickHouse-Datenbanktools aktivieren/deaktivieren
    • Standard: "true"
    • Auf "false" setzen, um ClickHouse-Tools bei ausschließlicher Verwendung von chDB zu deaktivieren
  • CLICKHOUSE_ALLOW_WRITE_ACCESS: Schreibvorgänge (DDL und DML) für ClickHouse zulassen
    • Standard: "false"
    • Auf "true" setzen, um nicht destruktive DDL- und DML-Vorgänge zuzulassen (CREATE, INSERT, ALTER ADD COLUMN). Für destruktive Anweisungen ist zusätzlich CLICKHOUSE_ALLOW_DROP=true erforderlich.
    • Wenn deaktiviert (Standard), werden Abfragen mit der Einstellung readonly=1 ausgeführt, um Datenänderungen zu verhindern
  • CLICKHOUSE_ALLOW_DROP: Destruktive Vorgänge zulassen (beliebige DROP oder TRUNCATE, DELETE und UPDATE, einschließlich der Varianten ALTER TABLE, REPLACE TABLE / REPLACE PARTITION / CREATE OR REPLACE, CLEAR COLUMN / CLEAR INDEX / CLEAR PROJECTION sowie DETACH ... PERMANENTLY)
    • Standard: "false"
    • Wird nur wirksam, wenn auch CLICKHOUSE_ALLOW_WRITE_ACCESS=true festgelegt ist
    • Diese Sperre ist eine bestmögliche Schutzmaßnahme gegen versehentliche Vorgänge im MCP-Server, aber keine Sicherheitsgrenze. Beschränken Sie die Berechtigungen des ClickHouse-Benutzers, um eine tatsächliche Durchsetzung zu gewährleisten (siehe Schutz vor destruktiven Vorgängen)
ClickHouse-TLS-Zertifikatsdateien

Die Zertifikatsvariablen enthalten Dateipfade, keine PEM-Inhalte. mcp-clickhouse übergibt diese Pfade an clickhouse-connect. Binden Sie Zertifikat und privaten Schlüssel für Docker oder Kubernetes als schreibgeschützte Dateien ein und verwenden Sie ihre Pfade innerhalb des Containers. Betten Sie keinen privaten Schlüssel in ein Image ein, übertragen Sie ihn nicht in die Quellcodeverwaltung und legen Sie seinen Inhalt nicht in einer Umgebungsvariablen ab.

Im Modus mutual identifiziert das konfigurierte Clientzertifikat diesen mcp-clickhouse-Prozess als CLICKHOUSE_USER. Es authentifiziert keine eingehenden MCP-Clients und übermittelt deren Identitäten nicht an ClickHouse. Konfigurieren Sie die MCP-Transportauthentifizierung separat.

Starten Sie mcp-clickhouse neu, nachdem Sie ein Zertifikat oder einen Schlüssel am selben Pfad ersetzt haben, wenn eine sofortige Rotation oder Sperrung erforderlich ist. Zwischengespeicherte Clients können bestehende TLS-Verbindungen beibehalten, und der Cache verfolgt weder Dateiinhalt noch Änderungszeiten.

ClickHouse Cloud unterstützt keine X.509-Clientzertifikatsauthentifizierung für Datenbankbenutzer. Verwenden Sie für ClickHouse Cloud CLICKHOUSE_USER und CLICKHOUSE_PASSWORD. Ein CA-Zertifikat kann weiterhin nützlich sein, wenn ein privater Proxy vor einem Endpunkt ein von einer privaten CA signiertes Zertifikat vorlegt.

MCP-Server und Transport

Diese Variablen steuern den MCP-Prozess selbst, einschließlich Transport, Authentifizierung und Ausführungslimits für Abfragetools. Sie sind unabhängig von den oben genannten ClickHouse-Datenbankeinstellungen. Siehe auch Authentifizierung für HTTP/SSE-Transporte.

  • CLICKHOUSE_MCP_SERVER_TRANSPORT: Legt die Transportmethode für den MCP-Server fest
    • Standard: "stdio"
    • Gültige Optionen: "stdio", "http", "sse". Dies ist für die lokale Entwicklung mit Tools wie MCP Inspector nützlich.
    • stdio ist typisch für Claude Desktop; http/sse stellen einen Netzwerk-Listener bereit (Bind-Host/-Port siehe unten)
    • "sse" wählt den veralteten eigenständigen HTTP+SSE-Transport aus und protokolliert eine Warnung. Verwenden Sie "http" für Streamable HTTP bei neuen Bereitstellungen.
  • CLICKHOUSE_MCP_BIND_HOST: Host, an den der MCP-Server bei Verwendung des HTTP- oder SSE-Transports 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 den Fernzugriff)
    • Wird nur verwendet, wenn der Transport "http" oder "sse" ist — hat nichts mit CLICKHOUSE_HOST zu tun
  • CLICKHOUSE_MCP_BIND_PORT: Port, an den der MCP-Server bei Verwendung des HTTP- oder SSE-Transports gebunden wird
    • Standard: "8000"
    • Wird nur verwendet, wenn der Transport "http" oder "sse" ist — hat nichts mit CLICKHOUSE_PORT zu tun
  • CLICKHOUSE_MCP_QUERY_TIMEOUT: Timeout in Sekunden für Aufrufe des Abfragetools
    • Standard: "30"
    • Erhöhen Sie diesen Wert, wenn bei umfangreichen Abfragen Query timed out after ...-Fehler auftreten
    • Bei einem Timeout einer Abfrage versucht der Server, sie mit KILL QUERY abzubrechen
    • Sofern CLICKHOUSE_SEND_RECEIVE_TIMEOUT nicht ausdrücklich festgelegt ist, wird das HTTP-Lese-Timeout auf diesen Wert plus fünf Sekunden begrenzt
  • CLICKHOUSE_MCP_MAX_WORKERS: Maximale Anzahl gleichzeitiger Abfrage-Worker-Threads
    • Standard: "10"
    • Erhöhen Sie den Wert, wenn Ihre Arbeitslast viele gleichzeitige Tool-Aufrufe erfordert
    • Metadaten-Tools verwenden einen separaten Pool mit min(4, CLICKHOUSE_MCP_MAX_WORKERS) Threads, damit die Schemaermittlung Abfragen nicht verzögert
  • CLICKHOUSE_MCP_AUTH_TOKEN: Statisches Bearer-Token für HTTP/SSE-Transporte
    • Standard: None
    • Für HTTP/SSE-Transporte ist einer der Werte CLICKHOUSE_MCP_AUTH_TOKEN, FASTMCP_SERVER_AUTH oder CLICKHOUSE_MCP_AUTH_DISABLED=true erforderlich
    • Generieren Sie das Token mit uuidgen oder openssl rand -hex 32
    • Clients müssen dieses Token im Header Authorization: Bearer <token> senden
  • FASTMCP_SERVER_AUTH: Authentifizierung an einen FastMCP-Authentifizierungsanbieter delegieren
    • Standard: None
    • Der Wert ist der vollständige Klassenpfad einer AuthProvider-Unterklasse, z. B. fastmcp.server.auth.providers.azure.AzureProvider oder fastmcp.server.auth.providers.google.GoogleProvider
    • Wenn diese Option gesetzt ist, lädt mcp-clickhouse den Anbieter aus den vorhandenen Umgebungsvariablen FASTMCP_SERVER_AUTH_*; lassen Sie in diesem Modus CLICKHOUSE_MCP_AUTH_TOKEN unset
    • Benutzerdefinierte Anbieter erhalten keine aus der Umgebung abgeleiteten Konstruktorargumente und müssen ohne Argumente instanziiert werden können
    • FastMCP 4 unterstützt keine Supabase-HS256-Verifizierung mehr. Supabase-Bereitstellungen müssen RS256 oder ES256 verwenden.
  • FASTMCP_ENV_FILE: Optionale Datei mit FASTMCP_SERVER_AUTH und anbieterspezifischen Umgebungsvariablen
    • Standard: None. Wenn nicht gesetzt, liest der Kompatibilitätslader fehlende Anbieterfelder aus .env im Arbeitsverzeichnis. Aus diesem Fallback liest er FASTMCP_SERVER_AUTH nicht
    • Legen Sie den Wert vor dem Start in der Prozessumgebung fest. Ein aus der Standarddatei .env geladener Wert kann den Kompatibilitätslader nicht umleiten
    • Wenn der Wert im Prozess gesetzt ist, kann diese Datei sowohl FASTMCP_SERVER_AUTH als auch Anbieterfelder enthalten und ersetzt den Fallback im Arbeitsverzeichnis
    • Werte aus der Prozessumgebung haben unabhängig von der Groß-/Kleinschreibung Vorrang
    • Der Kompatibilitätslader von mcp-clickhouse liest diese Datei nur beim Einrichten der HTTP/SSE-Authentifizierung und berücksichtigt nur die Einträge FASTMCP_SERVER_AUTH und FASTMCP_SERVER_AUTH_*. FastMCP 4 kann dieselbe Datei für seine umfassenderen Einstellungen lesen
    • Das Laden der Standarddatei .env erfolgt separat. Es beginnt im installierten Paketverzeichnis von mcp_clickhouse, löst symbolische Links auf, geht bis zum Dateisystemstamm nach oben und lädt die erste gefundene Datei .env oder keine Datei. Das Arbeitsverzeichnis wird unabhängig von der Startmethode niemals gelesen. Diese Datei kann neben anderen Servereinstellungen auch FASTMCP_SERVER_AUTH und Anbieterfelder enthalten. Bei einem ausgecheckten Quellcode wird normalerweise die Datei .env im Repository-Stamm gefunden
  • CLICKHOUSE_MCP_AUTH_DISABLED: Authentifizierung für HTTP/SSE-Transporte deaktivieren
    • Standard: "false" (Authentifizierung ist aktiviert)
    • Auf "true" setzen, um die Authentifizierung nur für lokale Entwicklung und Tests zu deaktivieren
    • WARNUNG: Nur für die lokale Entwicklung verwenden. Bei Netzwerkzugriff nicht deaktivieren
  • CLICKHOUSE_MCP_ALLOWED_HOSTS: Durch Kommas getrennte Host-Headerwerte, auf die der HTTP/SSE-Server antwortet
    • Standardwert für eine Loopback-Bindung: Formen ohne Port und mit beliebigem Port von 127.0.0.1, localhost und [::1]
    • Wenn gesetzt, muss der Wert mindestens einen Host-Eintrag enthalten.
    • Bei einer konkreten Nicht-Loopback-Bindadresse sind standardmäßig diese Adresse und der konfigurierte Port zulässig. Für eine Wildcard-Bindung wie 0.0.0.0 oder :: ist ein expliziter, nicht leerer Wert erforderlich, da sich der öffentliche Host nicht ableiten lässt.
    • Die Host-Validierung bietet zusätzlichen Schutz vor DNS-Rebinding. Die unten beschriebene Origin-Validierung ist gemäß MCP separat erforderlich.
    • Einträge sind exakt (localhost:8000) oder akzeptieren jeden Port (localhost:*). Beispiel: CLICKHOUSE_MCP_ALLOWED_HOSTS=127.0.0.1:8000,localhost:8000
    • Die Form host:* stimmt nur mit Werten überein, die einen Port enthalten. Ein Host ohne Port (bei einer Bereitstellung mit Standardport, wenn der Client :80/:443 weglässt) muss zusätzlich als exakter Eintrag ohne Port (example.com) aufgeführt werden.
    • Anfragen mit einem nicht übereinstimmenden oder fehlenden Header Host erhalten 421 Misdirected Request. GET- und HEAD-Anfragen an /health sind von der Host- und Origin-Validierung ausgenommen, damit Orchestrator-Prüfungen weiterhin funktionieren.
    • Hinter einem Reverse-Proxy sollte der ursprüngliche Header Host möglichst erhalten bleiben. Alternativ können Sie den Upstream-Wert Host aufführen, den der Proxy sendet. Legen Sie eine explizite Liste fest, wenn ein Starter wie fastmcp run die Bind-Adresse für den Fernzugriff überschreibt.
    • mcp-clickhouse deaktiviert die separate Host- und Origin-Prüfung von FastMCP. FASTMCP_HTTP_HOST_ORIGIN_PROTECTION, FASTMCP_HTTP_ALLOWED_HOSTS und FASTMCP_HTTP_ALLOWED_ORIGINS gelten nicht. CLICKHOUSE_MCP_ALLOWED_HOSTS und CLICKHOUSE_MCP_ALLOWED_ORIGINS sind maßgeblich.
  • CLICKHOUSE_MCP_TRUSTED_PROXIES: Proxy-IP-Adressen oder CIDR-Netzwerke, deren Header X-Forwarded-* als vertrauenswürdig gelten
    • Standard: None. X-Forwarded-Host wird ignoriert. Das bestehende Uvicorn-Verhalten für X-Forwarded-For und X-Forwarded-Proto bleibt unverändert.
    • Einträge müssen IP-Adressen oder CIDR-Netzwerke sein, z. B. 127.0.0.1,10.20.0.0/24,2001:db8::1. CIDRs müssen ihre Netzwerkadresse verwenden; daher wird 10.20.0.1/24 abgelehnt. Hostnamen, IPv6-Adressen mit Bereichskennung, *, 0.0.0.0/0 und ::/0 werden ebenfalls abgelehnt.
    • Das Vertrauen basiert auf dem unmittelbaren Peer des rohen Sockets. Bei einer Anfrage von einem anderen Peer oder ohne Clientadresse werden X-Forwarded-Host ignoriert und Host validiert.
    • Ein vertrauenswürdiger Peer darf genau einen Header X-Forwarded-Host mit einem nicht leeren Wert senden. Doppelte Felder, leere Werte und durch Kommas getrennte Listen führen zu 421 Misdirected Request. Fehlt der Header, wird Host validiert.
    • Verwenden Sie die engstmögliche Adresse oder das engstmögliche Netzwerk. Der MCP-Server darf nur über Proxys in den konfigurierten Bereichen erreichbar sein. Jeder vertrauenswürdige Proxy muss vom Client bereitgestellte Werte für X-Forwarded-Host und X-Forwarded-Proto entfernen und überschreiben sowie X-Forwarded-For anhand des verifizierten Verbindung-Peers erstellen.
    • Der integrierte Server und fastmcp run deaktivieren die äußere Proxy-Header-Verarbeitung von Uvicorn, validieren den Host anhand des rohen Peers und wenden anschließend X-Forwarded-For und X-Forwarded-Proto an. Wird uvicorn_config["proxy_headers"] in diesem Modus ausdrücklich aktiviert, schlägt der Start fehl.
    • Bei direkter ASGI-Einbettung muss die Proxy-Header-Verarbeitung im äußeren ASGI-Server deaktiviert und mcp.http_app(raw_client_address_preserved=True) aufgerufen werden. Ohne diese ausdrückliche Bestätigung schlägt die App-Erstellung fehl, wenn vertrauenswürdige Proxys konfiguriert sind.
  • CLICKHOUSE_MCP_ALLOWED_ORIGINS: Durch Kommas getrennte Origin-Headerwerte, die über HTTP/SSE akzeptiert werden
    • Standard: None; dadurch wird jede Anfrage abgelehnt, die einen Header Origin enthält
    • MCP erfordert eine Origin-Validierung für HTTP/SSE-Transportverbindungen. Anfragen ohne Origin werden akzeptiert, da MCP-Clients außerhalb von Browsern diesen Header normalerweise weglassen. Eine nicht übereinstimmende Origin führt zu 403 Forbidden. Der Endpunkt /health ist wie oben beschrieben ausgenommen.
    • Einträge sind exakt (http://localhost:3000) oder akzeptieren jeden Port (http://localhost:*). Wie bei Hosts stimmt die Form für beliebige Ports nur mit Origins überein, die einen Port enthalten; eine Origin mit Standardport (https://app.example.com) muss exakt aufgeführt werden.
Host-Verarbeitung durch Reverse-Proxys

Erhalten Sie Host nach Möglichkeit. Dadurch bleibt das Vertrauen in weitergeleitete Hosts deaktiviert:

location / {
    proxy_pass http://mcp-clickhouse:8000;
    proxy_set_header Host $http_host;
    proxy_set_header X-Forwarded-Host "";
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Bereinigen Sie X-Forwarded-For und X-Forwarded-Proto unabhängig vom Vertrauen in X-Forwarded-Host. Uvicorn kann diesen Headern basierend auf dem Proxy-Peer vertrauen, auch wenn CLICKHOUSE_MCP_TRUSTED_PROXIES nicht gesetzt ist.

CLICKHOUSE_MCP_ALLOWED_HOSTS=mcp.example.com

Standard-nginx ändert Host bei Proxy-Anfragen in den Upstream-Namen. Es erstellt oder überschreibt X-Forwarded-Host nicht. Wenn Host nicht erhalten bleiben kann, überschreiben Sie den weitergeleiteten Header am vertrauenswürdigen Rand:

location / {
    proxy_pass http://mcp-clickhouse:8000;
    proxy_set_header X-Forwarded-Host $http_host;
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;
}

CLICKHOUSE_MCP_ALLOWED_HOSTS=mcp.example.com
CLICKHOUSE_MCP_TRUSTED_PROXIES=10.20.0.8

Die zweite Konfiguration ist nur dann sicher, wenn 10.20.0.8 die unmittelbare Quelladresse des Proxys ist, der Server-Port von anderen Clients abgeschirmt ist und nginx die eingehenden Weiterleitungs-Header wie gezeigt überschreibt. Bei einer Proxy-Kette muss jeder vertrauenswürdige Hop nicht verifizierte eingehende Werte verwerfen, bevor er neue Weiterleitungs-Header erstellt.

Bei einer IPv6- oder Dual-Stack-Bindung können IPv4-Proxys als IPv4-zugeordnete Adressen wie ::ffff:10.20.0.8 erscheinen; diese werden automatisch mit IPv4-Einträgen abgeglichen. Envoys append_x_forwarded_host hängt Werte an einen vorhandenen X-Forwarded-Host an, statt ihn zu überschreiben. Dadurch entsteht eine durch Kommas getrennte Liste, die abgelehnt wird. Konfigurieren Sie den vertrauenswürdigen Hop daher so, dass er den Header überschreibt. Bei Kubernetes mit Source NAT (z. B. externalTrafficPolicy: Cluster) kann der beobachtete Peer eine Knoten-IP statt des Proxy-Pods sein. Vertrauen Sie daher je nach Bedarf dem Pod- oder Knoten-CIDR; ingress-nginx überschreibt Host und X-Forwarded-Host selbst.

Middleware-Variablen

  • MCP_MIDDLEWARE_MODULE: Name des Python-Moduls mit benutzerdefinierter Middleware, die in den MCP-Server eingebunden werden soll
    • Standard: None (keine Middleware geladen)
    • Legen Sie den Modulnamen Ihrer Middleware (ohne die Erweiterung .py) fest
    • Das Modul muss eine Funktion setup_middleware(mcp) bereitstellen
    • Einzelheiten und Beispiele finden Sie unter Benutzerdefinierte Middleware

chDB-Variablen

  • CHDB_ENABLED: chDB-Funktionalität aktivieren/deaktivieren
    • Standard: "false"
    • Auf "true" setzen, um chDB-Tools zu aktivieren
    • Erfordert die Installation des optionalen Extras: mcp-clickhouse[chdb]
    • Unter Python 3.15 kann ein unabhängig installiertes chDB den Prozess beenden, wenn CHDB_ENABLED=true.
  • CHDB_DATA_PATH: Pfad zum chDB-Datenverzeichnis
    • Standard: ":memory:" (In-Memory-Datenbank)
    • Verwenden Sie :memory: für eine In-Memory-Datenbank
    • Verwenden Sie für dauerhafte Speicherung einen Dateipfad (z. B. /path/to/chdb/data)

Häufige Konfigurationsfehler

  • CLICKHOUSE_SECURE vs. MCP-/Ingress-TLS — Wenn Sie CLICKHOUSE_SECURE deaktivieren, weil sich der MCP-Server hinter einem Kubernetes-Ingress oder Reverse-Proxy befindet oder über einfaches HTTP erreichbar ist, wird dadurch die Datenbank-TLS nicht deaktiviert. Es ändert lediglich, wie dieser Prozess eine Verbindung zu ClickHouse herstellt. Konfigurieren Sie Ingress-TLS unabhängig von den Datenbank-Client-Einstellungen.
  • Native-Protokoll-Ports — CLICKHOUSE_PORT muss auf die HTTP-Schnittstelle von ClickHouse zeigen (standardmäßig 8123/8443). Die Ports 9000/9440 sind für das native TCP-Protokoll (clickhouse-client) vorgesehen und funktionieren mit diesem Server nicht.
  • Verwechslung von Hosts — CLICKHOUSE_HOST ist der Hostname der Datenbank. CLICKHOUSE_MCP_BIND_HOST ist ausschließlich die Adresse, an der der MCP-HTTP/SSE-Server lauscht.

Beispielkonfigurationen

Für die lokale Entwicklung mit Docker:

# Required variables
CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse

# Optional: Override defaults for local development
CLICKHOUSE_SECURE=false  # Uses port 8123 automatically
CLICKHOUSE_VERIFY=false

Für ClickHouse Cloud:

# Required variables
CLICKHOUSE_HOST=your-instance.clickhouse.cloud
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=your-password

# Optional: These use secure defaults
# CLICKHOUSE_SECURE=true  # Uses port 8443 automatically
# CLICKHOUSE_DATABASE=your_database

Für ClickHouse SQL Playground:

CLICKHOUSE_HOST=sql-clickhouse.clickhouse.com
CLICKHOUSE_USER=demo
CLICKHOUSE_PASSWORD=
# Uses secure defaults (HTTPS on port 8443)

Für eine private Server-CA ohne Client-Zertifikatsauthentifizierung:

CLICKHOUSE_HOST=your-secure-clickhouse.example.com
CLICKHOUSE_USER=your-user
CLICKHOUSE_PASSWORD=your-password
CLICKHOUSE_SECURE=true
CLICKHOUSE_VERIFY=true
CLICKHOUSE_CA_CERT=/run/secrets/clickhouse-ca.pem

Für die X.509-Client-Zertifikatsauthentifizierung von ClickHouse:

CLICKHOUSE_HOST=your-secure-clickhouse.example.com
CLICKHOUSE_USER=your-certificate-user
CLICKHOUSE_SECURE=true
CLICKHOUSE_CLIENT_CERT=/run/secrets/clickhouse-client.pem
CLICKHOUSE_CLIENT_CERT_KEY=/run/secrets/clickhouse-client-key.pem
# CLICKHOUSE_CA_CERT=/run/secrets/clickhouse-ca.pem  # Only for a private server CA
# CLICKHOUSE_TLS_MODE=mutual  # Optional. This is the default with a client certificate.

Für ein Client-Zertifikat, das von einem strikten TLS-Server verlangt wird, während ClickHouse die Basisauthentifizierung verwendet:

CLICKHOUSE_HOST=your-secure-clickhouse.example.com
CLICKHOUSE_USER=your-user
CLICKHOUSE_PASSWORD=your-password
CLICKHOUSE_SECURE=true
CLICKHOUSE_CLIENT_CERT=/run/secrets/clickhouse-client.pem
CLICKHOUSE_CLIENT_CERT_KEY=/run/secrets/clickhouse-client-key.pem
CLICKHOUSE_TLS_MODE=strict

Verwenden Sie stattdessen CLICKHOUSE_TLS_MODE=proxy, wenn ein TLS-terminierender Proxy das Clientzertifikat benötigt und ClickHouse weiterhin die Basic-Authentifizierung verwendet.

Nur für chDB (im Arbeitsspeicher):

# chDB configuration
CHDB_ENABLED=true
CLICKHOUSE_ENABLED=false
# CHDB_DATA_PATH defaults to :memory:

Für chDB mit persistentem Speicher:

# chDB configuration
CHDB_ENABLED=true
CLICKHOUSE_ENABLED=false
CHDB_DATA_PATH=/path/to/chdb/data

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

CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse
CLICKHOUSE_MCP_SERVER_TRANSPORT=http
CLICKHOUSE_MCP_BIND_HOST=0.0.0.0  # Bind to all interfaces
CLICKHOUSE_MCP_BIND_PORT=4200  # Custom port (default: 8000)
CLICKHOUSE_MCP_AUTH_TOKEN=your-generated-token  # One auth mode required for HTTP/SSE (or FASTMCP_SERVER_AUTH, or CLICKHOUSE_MCP_AUTH_DISABLED=true)
CLICKHOUSE_MCP_ALLOWED_HOSTS=127.0.0.1:4200,localhost:4200,mcp.example.com:4200  # Include every Host value clients and proxies send

Für die lokale Entwicklung mit HTTP-Transport (Authentifizierung deaktiviert):

CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse
CLICKHOUSE_MCP_SERVER_TRANSPORT=http
CLICKHOUSE_MCP_AUTH_DISABLED=true  # Only for local development!
CLICKHOUSE_MCP_ALLOWED_HOSTS=127.0.0.1:8000,localhost:8000

Bei Verwendung des HTTP-Transports wird der Server am konfigurierten Port ausgeführt (Standard: 8000). Zum Beispiel mit der obigen Konfiguration:

  • MCP-Endpunkt: http://localhost:8000/mcp
  • Gesundheitsprüfung: http://localhost:8000/health

Sie können diese Variablen in Ihrer Umgebung, in einer .env-Datei oder in der Claude Desktop-Konfiguration festlegen:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.12",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_DATABASE": "<optional-database>",
        "CLICKHOUSE_MCP_SERVER_TRANSPORT": "stdio",
        "CLICKHOUSE_MCP_BIND_HOST": "127.0.0.1",
        "CLICKHOUSE_MCP_BIND_PORT": "8000"
      }
    }
  }
}

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

Tests ausführen

uv sync --locked --extra dev # install dev dependencies
uv run ruff check . # run linting

docker compose -f test-services/docker-compose.yaml up -d # start ClickHouse
uv run pytest -v tests
uv run pytest -v tests/test_tool.py # ClickHouse only
# Python 3.10 through 3.14 only:
CHDB_ENABLED=true uv run --extra chdb pytest -v tests/test_chdb_tool.py # chDB only

YouTube-Übersicht

YouTube