ClickHouse

offiziell

Fragen Sie Ihren ClickHouse-Datenbankserver ab.

GitHub
877

Was kann man mit ClickHouse MCP machen?

  • SQL-Abfragen ausführen — Führen Sie schreibgeschütztes SQL auf Ihrem ClickHouse-Cluster über run_query aus, mit optionalen benannten params für sichere Parameterbindung.
  • Abfragepläne untersuchen — Verwenden Sie DESCRIBE und EXPLAIN ESTIMATE innerhalb von run_query, um Ergebnisschemata vorab anzuzeigen oder Lesevorgänge vor der Ausführung abzuschätzen.
  • Datenbanken auflisten — Listen Sie alle Datenbanken auf dem Cluster mit list_databases auf, um verfügbare Datenquellen zu entdecken.
  • Tabellen mit Filtern durchsuchen — Verwenden Sie list_tables mit like/not_like-Mustern und Paginierung über page_token, um Tabellen in beliebigen Datenbanken zu erkunden.
  • Eingebettetes chDB abfragen — Führen Sie SQL gegen die eingebettete Engine von chDB mit run_chdb_select_query aus, um Dateien, URLs oder Datenbanken 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 zustandslose Anfragen und server/discover. Bestehende Clients können weiterhin das Legacy-Protokoll aushandeln.

[!HINWEIS] 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 diese Clients unterstützen. Moderne Clients sollten den Header bei jeder POST-Anfrage senden.

Funktionen

ClickHouse-Tools

ClickHouse-Toolantworten sind JSON-codierte Zeichenfolgen. Ganzzahlen außerhalb von [-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 Bereich und boolesche Werte behalten ihre JSON-Typen.

  • run_query

    • SQL-Abfragen auf Ihrem ClickHouse-Cluster ausführen.
    • Eingabe: query (Zeichenfolge): Die auszuführende SQL-Abfrage.
    • Optionale Eingabe: params (Objekt): Benannte Werte für ClickHouse-{name:Type}-Platzhalter. Siehe Abfrageparameter.
    • Abfragen laufen standardmäßig im Nur-Lese-Modus (CLICKHOUSE_ALLOW_WRITE_ACCESS=false), aber Schreibvorgänge können bei Bedarf explizit aktiviert werden.
    • DESCRIBE (<query>) und EXPLAIN ESTIMATE <query> laufen ebenfalls hier und sind optionale Möglichkeiten, das Ergebnisschema einer Abfrage oder ihre geschätzten Lesevorgänge zu überprüfen. Siehe Überprüfen einer Abfrage vor der Ausführung.

  • list_databases

    • Alle Datenbanken auf Ihrem ClickHouse-Cluster auflisten.

  • list_tables

    • Tabellen in einer Datenbank mit Paginierung auflisten.
    • Erforderliche Eingabe: database (Zeichenfolge).
    • Optionale Eingaben:
      • like / not_like (Zeichenfolge): LIKE- oder NOT LIKE-Filter auf Tabellennamen anwenden.
      • page_token (Zeichenfolge): Einmaliges Token, das von einem vorherigen Aufruf zurückgegeben wird. Es wird bis zu einer Stunde aufbewahrt.
      • page_size (int, Standard 50): Anzahl der pro Seite zurückgegebenen Tabellen; muss größer als 0 sein.
      • include_detailed_columns (bool, Standard true): Wenn false, werden Spaltenmetadaten für leichtere Antworten weggelassen, während die vollständige create_table_query erhalten bleibt.
    • Antwortstruktur:
      • tables: Array von Tabellenobjekten für die aktuelle Seite.
      • next_page_token: Geben Sie diesen Einmalwert vor Ablauf zurück, um die nächste Seite abzurufen, oder null, wenn keine weiteren Tabellen vorhanden sind.
      • total_tables: Gesamtzahl der Tabellen, die den angegebenen Filtern entsprechen.

Abfrageparameter

Übergeben Sie Werte getrennt von SQL über das optionale params-Objekt:

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

Verwenden Sie ClickHouses {name:Type}-Platzhalter ohne Anführungszeichen. Halten Sie die öffnende geschweifte Klammer, den Namen und den Doppelpunkt benachbart, 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 Kompatibilität mit unterstützten Treiberversionen beginnen Sie Namen mit einem Buchstaben oder Unterstrich und verwenden Sie nur Buchstaben, Ziffern und Unterstriche. Python-Stil %s- oder %(name)s-Formatierung und die $name$-Rohbinärparameter des Treibers werden nicht unterstützt. Aufrufe mit nur query funktionieren weiterhin. Weglassen von params, Übergeben von null oder Übergeben eines leeren Objekts lässt 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 Nullable(...)-Typ.
  • Übergeben Sie exakte Ganzzahlen außerhalb des sicheren JavaScript-Bereichs als Dezimalzeichenfolgen, zum Beispiel "18446744073709551615" mit {id:UInt64}. Daten, Zeitstempel und exakte Dezimalzahlen können auch als Zeichenfolgen mit dem entsprechenden ClickHouse-Typ übergeben werden.
  • Binden Sie Vektoren als ein Array, zum Beispiel {vector:Array(Float32)} mit "params": {"vector": [0.25, 0.5, 0.75]}.
  • Nullen in Arrays hängen vom installierten Treiber ab. Sie funktionieren mit clickhouse-connect 1.8.0, schlagen aber mit dem unterstützten Minimum 1.0.0 fehl.
  • JSON-Listen und -Objekte können nicht an ClickHouse-Tuple- und Map-Typen gebunden werden.

Fehlende Werte und inkompatible Typen geben Abfragefehler zurück. Mit nicht leerem params, wird eine Abfrage mit vielen nicht abgeschlossenen {name:-Platzhalteranfängen abgelehnt, einschließlich platzhalterähnlichem Text in Kommentaren oder Zeichenfolgenliteralen. Parametrisierte Abfragen verwenden denselben Schreibschutz, dieselben Zeitüberschreitungen, denselben Abbruch und dieselbe JSON-Ergebniscodierung wie andere Abfragen.

Parameterwerte bleiben außerhalb der normalen SQL-Protokollmeldungen des MCP-Servers, bleiben jedoch in MCP-Toolargumenten und können in Backend-Fehlern erscheinen. ClickHouse 26.3.20.7 substituiert Werte in den Abfragetext in system.query_log, system.processes, und system.text_log. Parameterbindung ist keine Datenschutzfunktion und reduziert nicht die Anzahl der in einem Toolaufruf gesendeten Vektorwerte.

Überprüfen einer Abfrage vor der Ausführung

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

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

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 zu antworten, daher erscheinen Analysefehler hier mit ClickHouses eigener Meldung, anstatt 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, die sauber beschreibt, kann bei der Ausführung dennoch fehlschlagen, aufgrund eines Speicherlimits oder eines Remote-Serverfehlers, und sie sagt nichts über die Kosten aus.

EXPLAIN ESTIMATE <query> gibt die Teile, Zeilen und Markierungen zurück, die die Abfrage lesen würde, eine Zeile pro Tabelle, was einen Primärschlüssel-Lookup von einem vollständigen Scan unterscheidet:

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

database  table   parts  rows   marks
default   events  1      8192   1

Dies sind geschätzte Lesevorgänge aus MergeTree-Familientabellen nach Primärschlüssel- und Partitionsbereinigung. Sie sind keine Laufzeit und keine Ergebnisgröße, und andere Tabellen-Engines sind nicht abgedeckt.

Keine der 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 Standard-CLICKHOUSE_ALLOW_WRITE_ACCESS=false. Siehe die ClickHouse-Dokumentation für EXPLAIN ESTIMATE und DESCRIBE.

chDB-Tools

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

Health-Check-Endpunkt

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

  • Gibt 200 OK zurück (Body: OK), 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-Überprüfung nicht innerhalb von zwei Sekunden abgeschlossen wird. Gleichzeitige Anfragen teilen sich eine laufende Überprüfung
  • Verwendet ein abgeschlossenes Überprüfungsergebnis für eine Sekunde erneut, sodass Überprüfungen, die in schneller Folge eintreffen, nicht jeweils eine Verbindung zu ClickHouse herstellen. Ein Fehler oder eine Wiederherstellung kann daher bis zu einer Sekunde verzögert gemeldet werden

GET- und HEAD-Anfragen an den Endpunkt sind absichtlich nicht authentifiziert und von der Host- und Origin-Validierung ausgenommen, damit Orchestrator-Überprüfungen (z. B. Kubernetes-Liveness/Readiness, Load Balancer) Laufzeit-zugewiesene Pod- oder Ziel-IPs 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 das Durchsickern von Backend-Versionszeichenfolgen oder Fehlerdetails zu vermeiden; debuggen Sie Fehler über die Serverprotokolle.

Beispiel:

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

Sicherheit

Authentifizierung für HTTP/SSE-Transports

Bei Verwendung von HTTP- oder SSE-Transport ist die Authentifizierung standardmäßig erforderlich. Der stdio-Transport (Standard) erfordert keine Authentifizierung, da er nur über Standard-Eingabe/Ausgabe kommuniziert.

Drei Authentifizierungsmodi werden unterstützt. Wählen Sie einen:

ModusWann verwendenUmgebungsvariable
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> (+ anbieter-spezifische FASTMCP_SERVER_AUTH_*-Variablen)
DeaktiviertNur lokale EntwicklungCLICKHOUSE_MCP_AUTH_DISABLED=true

Der Start schlägt fehl, wenn keines davon für HTTP/SSE-Transports konfiguriert ist.

Einrichten der Authentifizierung

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

    # 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, um das Token in Anfragen aufzunehmen:

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

OAuth / OIDC über FastMCP

Für Produktionsbereitstellungen mit Identitätsanbietern (Azure Entra, Google, GitHub, WorkOS usw.) delegieren Sie die Authentifizierung an FastMCPs integrierte Auth-Anbieter, anstatt ein statisches Token zu verwenden. Setzen Sie FASTMCP_SERVER_AUTH auf den vollständigen Klassenpfad eines FastMCP-Auth-Anbieters, zusammen mit den anbieter-spezifischen 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 FastMCP 4.0.0 integrierten Anbieter bei:

Anbieter-KlassenpfadAnbieter-Variablenpräfix
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 Anbieterfeldnamen an das Präfix an. Siehe die FastMCP-Dokumentation für die Konfigurationsanforderungen jedes Anbieters.

Auth-Werte, die direkt in der Prozessumgebung gesetzt werden, haben Vorrang, wobei die Groß-/Kleinschreibung nicht beachtet wird. Der Standard-Ladevorgang von .env beginnt im installierten mcp_clickhouse-Paketverzeichnis, löst zuerst Symlinks auf und wandert nach oben bis zum Dateisystemstamm. Er lädt die erste gefundene .env und lädt nichts, wenn es keine gibt. Er liest niemals das Arbeitsverzeichnis, unabhängig davon, wie der Server gestartet wird. Ein Quellcode-Checkout findet normalerweise die .env im Repository-Stamm. Diese Datei kann auch FASTMCP_SERVER_AUTH und deren Provider-Felder bereitstellen. Ihre Werte haben Vorrang vor der expliziten oder Kompatibilitäts-Auth-Datei. Für die FastMCP-2-Kompatibilität liest mcp-clickhouse fehlende Provider-Felder aus .env im Arbeitsverzeichnis, aber dieser Kompatibilitäts-Fallback kann kein FASTMCP_SERVER_AUTH auswählen. Ein prozessgesetztes FASTMCP_ENV_FILE ersetzt diesen Kompatibilitäts- Fallback und kann sowohl den Selektor als auch die Provider-Felder bereitstellen. Setzen Sie es vor dem Start. Der mcp-clickhouse-Kompatibilitätslader liest nur FASTMCP_SERVER_AUTH und FASTMCP_SERVER_AUTH_* aus dieser Datei, sodass er keine CLICKHOUSE_*-Einstellungen injizieren kann. FastMCP 4 verwendet möglicherweise dieselbe Datei für seine eigenen umfassenderen Einstellungen. Ein benutzerdefinierter Provider erhält keine aus der Umgebung abgeleiteten Konstruktorargumente und muss eine Konstruktion ohne Argumente unterstützen.

Behandeln Sie sowohl gefundene als auch im Arbeitsverzeichnis befindliche .env-Dateien als vertrauenswürdige Authentifizierungs- konfiguration. Jeder, der eine .env in einem beliebigen Verzeichnis vom Paketverzeichnis bis zum Dateisystemstamm erstellen oder beschreiben kann, kann steuern, welche Datei gefunden wird, den Provider auswählen und dessen Felder festlegen. Jeder, der die Datei im Arbeitsverzeichnis beschreiben kann, kontrolliert jedes Provider-Feld, das in der Prozess- und gefundenen Konfiguration fehlt, einschließlich Signaturschlüsseln, Ausstellern und Endpunkten sowie Client-Geheimnissen. Ein prozessgesetztes FASTMCP_ENV_FILE, das auf eine vom Betreiber verwaltete Datei verweist, deaktiviert den Arbeitsverzeichnis-Fallback.

FastMCP 4 hat den Standard-OAuth-Proxy-Client-Speicher geändert. Bereitstellungen, die auf FastMCP 2s Standard-OAuth-Proxy-Speicher angewiesen waren, müssen Clients erneut registrieren und autorisieren. Kompatibler benutzerdefinierter Speicher, statische Bearer-Tokens und JWT-Verifizierung sind nicht betroffen.

Entwicklungsmodus (Deaktivieren der Authentifizierung)

Nur für die lokale Entwicklung und zum Testen 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 einem Netzwerk ausgesetzt ist.

Konfiguration

Dieser MCP-Server unterstützt sowohl ClickHouse als auch chDB. Sie können je nach Bedarf eines oder beide aktivieren. Python 3.10 bis 3.14 werden unterstützt. Python 3.12 wird für lokale Starts empfohlen.

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

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

  2. Fügen Sie 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, um auf Ihren eigenen ClickHouse-Dienst zu verweisen.

Oder, wenn Sie es 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ür chDB (eingebettete ClickHouse-Engine) fügen Sie 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 auch ClickHouse und chDB 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 uv-ausführbaren Datei. Dadurch wird sichergestellt, dass die richtige Version von uv beim Starten des Servers verwendet wird. Auf einem Mac finden Sie diesen Pfad mit which uv.

  2. Starten Sie Claude Desktop neu, um die Änderungen zu übernehmen.

Optionale Schreibzugriffe

Standardmäßig erzwingt dieser MCP schreibgeschützte Abfragen, sodass während der Erkundung keine versehentlichen Mutationen auftreten können. 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.

Schutz vor destruktiven Operationen

Selbst wenn der Schreibzugriff aktiviert ist (CLICKHOUSE_ALLOW_WRITE_ACCESS=true), erfordern destruktive Operationen aus Sicherheitsgründen ein zusätzliches Opt-in-Flag. Die Prüfung umfasst jede DROP-Anweisung (einschließlich der ALTER TABLE ... DROP PARTITION / DROP PART / DROP COLUMN-Klauseln), jede TRUNCATE, DELETE und UPDATE (sowohl die leichtgewichtigen Anweisungen als auch die ALTER TABLE ... DELETE / ALTER TABLE ... UPDATE-Mutationen), REPLACE TABLE, CREATE OR REPLACE, ALTER TABLE ... REPLACE PARTITION, ALTER TABLE ... CLEAR COLUMN / CLEAR INDEX / CLEAR PROJECTION und DETACH ... PERMANENTLY. Schlüsselwörter in Zeichenfolgenliteralen, in Anführungszeichen gesetzten Bezeichnern, SQL-Kommentaren und {name:Type}-Parameternamen werden ignoriert, sodass sie die Prüfung weder auslösen noch eine Anweisung davor verbergen.

Diese Prüfung läuft im MCP-Server und ist ein Best-Effort-Schutz gegen Unfälle. Sie ist keine Sicherheitsgrenze. Die Sicherheitsgrenze sind die Berechtigungen des ClickHouse-Benutzers. Der schreibgeschützte Modus (Standard) wird serverseitig über readonly=1 erzwungen. Das Tor für destruktive Operationen wird nicht servererzwungen.

Geben Sie dem MCP-Server für den Schreibmodus einen dedizierten ClickHouse-Benutzer mit nur den benötigten Berechtigungen:

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

Jede Anweisung außerhalb dieser Berechtigungen schlägt dann serverseitig mit ACCESS_DENIED fehl, unabhängig von MCP-Flags. Die Servereinstellungen max_table_size_to_drop und max_partition_size_to_drop können den Schadensradius ebenfalls begrenzen, wenn sie mit Einstellungsbeschränkungen festgelegt werden.

Um destruktive Operationen zu aktivieren, setzen Sie beide Flags:

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

Dieser zweistufige Ansatz macht versehentliches Löschen schwierig:

  • Schreiboperationen (INSERT, CREATE, ALTER ADD COLUMN) erfordern CLICKHOUSE_ALLOW_WRITE_ACCESS=true
  • Destruktive Operationen (DROP, TRUNCATE, DELETE, UPDATE und der Rest der obigen Liste) erfordern zusätzlich CLICKHOUSE_ALLOW_DROP=true

Ausführen ohne uv (mit System-Python)

Wenn Sie die System-Python-Installation anstelle von uv 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]'

    Um auf die neueste Version zu aktualisieren:

    python3 -m pip install --upgrade mcp-clickhouse

  2. Aktualisieren Sie Ihre Claude-Desktop-Konfiguration, um Python direkt zu verwenden:

{
  "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: Stellen Sie sicher, dass Sie den vollständigen Pfad zur Python-Ausführungsdatei oder zum mcp-clickhouse-Skript verwenden, wenn diese nicht in Ihrem System-PATH sind. Sie finden die Pfade mit:

  • which python3 für die Python-Ausführungsdatei
  • 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.

So verwenden Sie es

  1. Erstellen Sie ein Python-Modul mit Middleware-Klassen, die Middleware erweitern, und einer setup_middleware(mcp)-Funktion:
# 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 .py-Erweiterung):
{
  "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 Beispiel-Middleware-Modul wird in example_middleware.py bereitgestellt, das gängige Muster zeigt:

  • Protokollieren aller MCP-Anfragen
  • Protokollieren von Tool-Aufrufen im Speziellen
  • Messen der Anfrageverarbeitungszeit

Um das Beispiel zu verwenden:

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

Middleware-Funktionen

Die Middleware-Basisklasse bietet Hooks für verschiedene MCP-Operationen:

  • 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 aufgerufen, wenn ein Tool ausgeführt wird
  • on_read_resource(context, call_next) - Wird aufgerufen, wenn eine Ressource gelesen wird
  • on_get_prompt(context, call_next) - Wird aufgerufen, wenn ein Prompt abgerufen wird
  • 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 empfängt ein MiddlewareContext-Objekt, das die Nachricht und Metadaten enthält, sowie eine call_next-Funktion, um die Pipeline fortzusetzen.

Dynamische Client-Konfiguration über Kontextstatus

Middleware kann die ClickHouse-Client-Konfiguration pro Anfrage mithilfe des CLIENT_CONFIG_OVERRIDES_KEY-Kontextstatus-Schlüssels überschreiben. Der Server führt diese Überschreibungen mit der Basiskonfiguration aus 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)

Dies ermöglicht erweiterte Anwendungsfälle wie dynamische Timeout-Anpassungen, mandantenspezifisches Routing oder benutzerspezifische Verbindungseinstellungen.

Der Statuswert muss ein Wörterbuch sein. Verschachtelte settings- und generic_args-Werte müssen Zuordnungen sein und werden mit der Basiskonfiguration zusammengeführt. Ungültige Werte lassen den Tool-Aufruf fehlschlagen, bevor ein ClickHouse-Client erstellt wird. CLICKHOUSE_ROLE bleibt aktiv, es sei denn, die Überschreibung liefert explizit settings.role. Top-Level-role- und ch_role-Schlüssel sowie dieselben Schlüssel unter generic_args werden abgelehnt.

Setzen Sie verify, ca_cert, client_cert, client_cert_key, tls_mode, server_host_name, und pool_mgr nur als Top-Level-Überschreibungen. Sie können nicht unter generic_args verschachtelt werden. Ein benutzerdefiniertes pool_mgr kann nicht mit verwalteten CA- oder Client-Zertifikatseinstellungen kombiniert werden. DSN-Abfrage parameter können diese Schlüssel nicht setzen, und ein DSN kann das chdb-Backend nicht auswählen. Verwenden Sie explizite Top-Level-host, port, username, password, database- und secure-Überschreibungen, um die Verbindung zu ändern. Ein weitergeleitetes DSN ersetzt keine ausgefüllten Basisverbindungsfelder und wählt kein TLS aus. Es kann leere Felder füllen und unterstützte Abfrageparameter wie query_limit bereitstellen. secure- und verify-Überschreibungen akzeptieren boolesche Werte oder die Zeichenfolgen true und false. verify akzeptiert auch proxy, das sich wie tls_mode: proxy verhält, wenn tls_mode nicht gesetzt ist, und daher Basic-Authentifizierung mit dem Umgebungskennwort verwendet. Eine secure-Überschreibung wählt die passende https- oder http-Schnittstelle aus und ändert den Port nicht. Eine explizite interface-Überschreibung muss http oder https sein und mit secure übereinstimmen. Nach dem Zusammenführen von Überschreibungen lassen die Standard- und mutual-Client-Zertifikatsmodi das Kennwort weg. proxy- und strict-Modi verwenden Basic-Authentifizierung mit dem Umgebungskennwort, es sei denn, die Überschreibung liefert eigene Anmeldeinformationen.

Behandeln Sie diese Überschreibungen als vertrauenswürdige Middleware-Eingaben. Middleware muss anfrageabgeleitete Werte authentifizieren und autorisieren, bevor sie sie festlegt. Verwenden Sie serializable=False, damit FastMCP den Wert im anfragelokalen Status behält. Der Standard-serializable=True speichert Sitzungsstatus und wird vom Server abgelehnt. Der Server erstellt eine Momentaufnahme des Werts, bevor er blockierende Datenbankarbeit verteilt. Speichern Sie keine Mandantendaten im sitzungsbezogenen Kontextstatus. Eine abgelehnte sitzungsbezogene Überschreibung bleibt an einer Legacy-MCP-Sitzung hängen und führt dazu, dass spätere Tool-Aufrufe in dieser Sitzung fehlschlagen, bis der Client erneut eine Verbindung herstellt. Eine pro Anfrage festgelegte ClickHouse-Rolle ist Verbindungskonfiguration, keine Mandanten-Autorisierungsgrenze. Erzwingen Sie Mandantenisolation 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 .env-Datei im Stammverzeichnis des Repositorys hinzu.

Hinweis: Die Verwendung des default-Benutzers in diesem Kontext ist ausschließlich für lokale Entwicklungszwecke gedacht.

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

  1. Führen Sie uv sync aus, um die Abhängigkeiten zu installieren. Um uv zu installieren, befolgen Sie die Anweisungen hier. Führen Sie dann source .venv/bin/activate aus.

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

  3. Zum Testen mit HTTP-Transport und dem 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 Modullayout. Beginnen Sie mit mcp_server.py für die Server-Assemblierung und -Registrierung, und folgen Sie dann der Implementierung in ihr zugehöriges Modul.

ModulVerantwortlichkeit
mcp_server.py, main.pyStart-Assemblierung, Tool- und Prompt-Registrierung, Shutdown-Koordination und CLI-Start
clients.pyAnfragekonfiguration, gecachte ClickHouse-Verbindungen und Client-Leases
queries.pyAbfrageausführung, Abbruch und Schutzmechanismen für destruktive Operationen
metadata.pyDatenbank- und Tabellenermittlung, Metadatenmodelle und Paginierung
chdb_backend.py, chdb_prompt.pyOptionale chDB-Initialisierung, Abfrageausführung und Prompt-Inhalte
health.py, executors.pyHealth-Probes und Caching sowie die von Serveroperationen verwendeten Worker-Pools
auth.py, transport.py, http_security.pyDotenv-Laden, Authentifizierung, HTTP/SSE-App-Konstruktion und Host/Origin-Validierung
mcp_env.py, serialization.pyUmgebungskonfiguration und JSON-Ergebnis-Kodierung
mcp_middleware_hook.py, skills_advisor.pyBenutzerdefiniertes Middleware-Laden und Serveranweisungen

Jede Server-Assemblierung besitzt ihre eigenen Worker-Pools, den Client-Cache, aktive Abfragen, den Paginierungs-Cache, den Health-Zustand und das chDB-Backend. Worker- und Client-Bereinigung erfolgt beim Prozessende. Paketimporte initialisieren den Standard-Server, auch beim ersten Import eines extrahierten Moduls.

In Tests patchen Sie das Modul oder die Owner-Instanz, wo der Code eine Abhängigkeit liest. Beispielsweise patchen Sie mcp_clickhouse.clients.clickhouse_connect.get_client für die Client-Erstellung. Kompatibilitäts- Importe in mcp_server.py können separate Bindungen von denen sein, die eine Implementierung verwendet.

Umgebungsvariablen

Die Konfiguration ist in unabhängige Gruppen aufgeteilt. Diese zu verwechseln ist eine häufige Ursache für schwer zu debuggende 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 nur für die ausgehende ClickHouse-Datenbank-Verbindung. Sie konfigurieren nicht TLS, Client-Zertifikate, Ports oder Authentifizierung für den eingehenden MCP-HTTP/SSE-Endpunkt.

Beispiel: Wenn der MCP-Server in Kubernetes hinter einem Ingress läuft, der TLS terminiert, ist das ein MCP-Transport-Thema. Halten Sie CLICKHOUSE_SECURE im Einklang damit, wie der Pod ClickHouse selbst erreicht (HTTPS → true, einfaches HTTP → false). Das Setzen von CLICKHOUSE_SECURE=false, weil der MCP-Server hinter einem Ingress liegt, führt dazu, dass der Server ClickHouse über HTTP anwählt – oft gegen einen HTTPS-only-Port – und undurchsichtige HTTP/TLS-Fehler in den Server-Logs erzeugt.

ClickHouse-Datenbankverbindung

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

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

[!CAUTION] Es ist wichtig, Ihren MCP-Datenbankbenutzer wie jeden externen Client zu behandeln, der sich mit Ihrer Datenbank verbindet, und ihm nur die minimal notwendigen Berechtigungen zu gewähren, die für seinen Betrieb erforderlich sind. Die Verwendung von Standard- oder administrativen Benutzern sollte zu jeder Zeit strikt 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 gesetzt werden, es sei denn, ein nicht standardmäßiger Port wird verwendet
    • Muss ein HTTP-Schnittstellenport sein, nicht der native TCP-Protokollport, der von clickhouse-client verwendet wird
    • Häufige Werte:
      • HTTP: 8123 (einfach) / 8443 (TLS) – von diesem Server und ClickHouse Cloud HTTPS verwendet
      • Natives TCP (hier nicht unterstützt): 9000 (einfach) / 9440 (TLS) – von clickhouse-client verwendet
    • Wenn der Server mit Port 9000 is for clickhouse-client program antwortet, sind Sie auf das native Protokoll ausgerichtet; wechseln Sie zum HTTP-Port (8123/8443 oder das HTTP-Mapping Ihrer Bereitstellung)
  • CLICKHOUSE_ROLE: Die ClickHouse-Rolle, die für die Authentifizierung verwendet werden soll
    • Standard: Keine
    • Setzen Sie dies, wenn Ihr Benutzer eine bestimmte Rolle erfordert
  • CLICKHOUSE_SECURE: HTTPS für die ClickHouse-Datenbankverbindung aktivieren (nicht für MCP-Clients)
    • Standard: "true"
    • Setzen Sie es auf "false" nur, wenn der MCP-Server ClickHouse über einfaches HTTP erreicht (typisch für lokales Docker Compose auf Port 8123)
    • Lassen Sie "true" für ClickHouse Cloud und jeden HTTPS-Datenbank-Endpunkt – selbst wenn der MCP-Server selbst über HTTP, stdio oder einen Ingress, der TLS separat terminiert, bereitgestellt wird
    • Ein Nichtübereinstimmen dieses Flags mit dem Datenbankport (z. B. CLICKHOUSE_SECURE=false gegen Port 8443) ist ein häufiger Einrichtungsfehler und erscheint normalerweise als verwirrende HTTP-Client-Fehler und nicht als klare "falsches Schema"-Meldung
  • CLICKHOUSE_VERIFY: SSL-Zertifikatsprüfung für die ClickHouse-HTTPS-Verbindung aktivieren/deaktivieren
    • Standard: "true"
    • Setzen Sie es auf "false", um die Zertifikatsprüfung zu deaktivieren (nicht für die Produktion empfohlen)
    • TLS-Zertifikate: Das Paket verwendet den Trust-Store Ihres Betriebssystems über truststore.inject_into_ssl() beim Start. Pythons Standard-SSL-Handhabung wird verwendet, wenn die Injektion mit MCP_CLICKHOUSE_TRUSTSTORE_DISABLE=1 deaktiviert ist oder fehlschlägt.
  • MCP_CLICKHOUSE_TRUSTSTORE_DISABLE: Die prozessweite Integration des Betriebssystem-Trust-Stores für TLS deaktivieren
    • Standard: nicht gesetzt (Trust-Store-Integration ist aktiviert)
    • Setzen Sie es vor dem Start auf genau "1", um truststore.inject_into_ssl() zu überspringen und Pythons Standard-SSL-Zertifikatshandhabung zu verwenden. Andere Werte deaktivieren die Integration nicht.
    • Dies deaktiviert nicht die Zertifikatsprüfung. CLICKHOUSE_VERIFY steuert weiterhin die Prüfung für die ClickHouse-HTTPS-Verbindung.
  • CLICKHOUSE_CA_CERT: Pfad zu einem PEM-CA-Zertifikatsbündel für die ClickHouse-HTTPS-Verbindung
    • Standard: Keine (verwendet den Trust-Store des Betriebssystems, es sei denn, die Truststore-Injektion ist deaktiviert oder schlägt fehl)
    • Verwenden Sie dies allein, wenn ein ClickHouse-Server oder ein privater Proxy ein Zertifikat präsentiert, das von einer privaten CA signiert ist. Dies ändert die Serverzertifikatsprüfung und aktiviert keine Client-Zertifikatsauthentifizierung.
    • Erfordert CLICKHOUSE_SECURE=true und CLICKHOUSE_VERIFY=true
  • CLICKHOUSE_CLIENT_CERT: Pfad zu einem PEM-Client-Zertifikat für die ClickHouse-HTTPS-Verbindung
    • Standard: Keine
    • Die Datei kann auch den privaten Schlüssel enthalten. Andernfalls setzen Sie CLICKHOUSE_CLIENT_CERT_KEY.
    • Der ClickHouse-Benutzer stammt weiterhin aus CLICKHOUSE_USER.
  • CLICKHOUSE_CLIENT_CERT_KEY: Pfad zum PEM-privaten Schlüssel für CLICKHOUSE_CLIENT_CERT
    • Standard: Keine
    • Optional, wenn der private Schlüssel in der Client-Zertifikatsdatei enthalten ist
    • Kann nicht ohne CLICKHOUSE_CLIENT_CERT verwendet werden
  • CLICKHOUSE_TLS_MODE: Wie clickhouse-connect CLICKHOUSE_CLIENT_CERT verwendet
    • Standard: Keine, was sich wie "mutual" verhält, wenn ein Client-Zertifikat gesetzt ist
    • "mutual": Verwenden Sie das Client-Zertifikat für die ClickHouse-X.509-Benutzerauthentifizierung. CLICKHOUSE_PASSWORD ist optional und wird nicht gesendet.
    • "proxy": Präsentieren Sie das Client-Zertifikat einem TLS-terminierenden Proxy und verwenden Sie dann die ClickHouse-Basic-Authentifizierung. CLICKHOUSE_PASSWORD ist erforderlich.
    • "strict": Präsentieren Sie das Client-Zertifikat, weil der ClickHouse-Server eines auf der TLS-Ebene erfordert, und verwenden Sie dann die ClickHouse-Basic-Authentifizierung. CLICKHOUSE_PASSWORD ist erforderlich. Dieser Modus verstärkt die Serverzertifikatsprüfung nicht. CLICKHOUSE_VERIFY steuert diese Prüfung.
    • clickhouse-connect behandelt "proxy" und "strict" identisch. Die beiden Namen dokumentieren die Absicht.
    • Werte werden getrimmt und sind case-insensitiv. Ein leerer Wert wird als nicht gesetzt behandelt. Andere Werte werden abgelehnt, bevor ein ClickHouse-Client erstellt wird, beim ersten ClickHouse-Toolaufruf oder /health-Probe.
    • Erfordert CLICKHOUSE_CLIENT_CERT. Alle Client-Zertifikatsoptionen erfordern CLICKHOUSE_SECURE=true.
  • CLICKHOUSE_SERVER_HOST_NAME: Server-Hostname für SNI-Override und Zertifikatsvalidierung auf der ClickHouse-Verbindung
    • Standard: Keine (verwendet den Verbindungshostnamen)
    • Dies ist nützlich, wenn Sie sich über Proxys oder Load Balancer verbinden, bei denen der Zertifikatshostname vom Verbindungshostnamen abweicht. Wenn gesetzt, wird dieser Hostname sowohl für SNI (Server Name Indication) während des TLS-Handshakes als auch für die Zertifikatshostnamen-Validierung verwendet.
  • CLICKHOUSE_PROXY_PATH: URL-Pfadpräfix für den ClickHouse-HTTP-Endpunkt
    • Standard: Keine
    • Setzen Sie dies, 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 Sie Verbindungs-Timeouts erleben
  • CLICKHOUSE_SEND_RECEIVE_TIMEOUT: Sende-/Empfangs-Timeout in Sekunden für den ClickHouse-Client
    • Standard: der niedrigere von 300 oder CLICKHOUSE_MCP_QUERY_TIMEOUT + 5, sodass Worker-Threads kurz nach einem Abfrage-Timeout entsperrt werden
    • Wenn explizit gesetzt, wird der Wert unverändert verwendet (z. B. "300" für langlaufende Abfragen)
  • CLICKHOUSE_DATABASE: Standard-ClickHouse-Datenbank, die verwendet werden soll
    • Standard: Keine (verwendet den Serverstandard)
    • Setzen Sie dies, um automatisch eine Verbindung zu einer bestimmten Datenbank herzustellen
  • CLICKHOUSE_ENABLED: ClickHouse-Datenbank-Tools aktivieren/deaktivieren
    • Standard: "true"
    • Setzen Sie es auf "false", um ClickHouse-Tools zu deaktivieren, wenn nur chDB verwendet wird
  • CLICKHOUSE_ALLOW_WRITE_ACCESS: Schreiboperationen (DDL und DML) gegen ClickHouse erlauben
    • Standard: "false"
    • Setzen Sie es auf "true", um nicht-destruktive DDL und DML zu erlauben (CREATE, INSERT, ALTER ADD COLUMN). Destruktive Anweisungen benötigen zusätzlich CLICKHOUSE_ALLOW_DROP=true
    • Wenn deaktiviert (Standard), werden Abfragen mit der readonly=1-Einstellung ausgeführt, um Datenänderungen zu verhindern
  • CLICKHOUSE_ALLOW_DROP: Destruktive Operationen erlauben (jede DROP oder TRUNCATE, DELETE und UPDATE einschließlich der ALTER TABLE-Varianten, REPLACE TABLE / REPLACE PARTITION / CREATE OR REPLACE, CLEAR COLUMN / CLEAR INDEX / CLEAR PROJECTION und DETACH ... PERMANENTLY)
    • Standard: "false"
    • Wirkt nur, wenn CLICKHOUSE_ALLOW_WRITE_ACCESS=true ebenfalls gesetzt ist
    • Diese Sperre ist ein Best-Effort-Unfallschutz im MCP-Server, keine Sicherheitsgrenze. Beschränken Sie die Berechtigungen des ClickHouse-Benutzers für echte Durchsetzung (siehe Schutz destruktiver Operationen)
ClickHouse-TLS-Zertifikatsdateien

Die Zertifikatsvariablen enthalten Dateipfade, keine PEM-Inhalte. mcp-clickhouse übergibt diese Pfade an clickhouse-connect. Für Docker oder Kubernetes mounten Sie das Zertifikat und den privaten Schlüssel als schreibgeschützte Dateien und verwenden Sie ihre Pfade im Container. Backen Sie keinen privaten Schlüssel in ein Image, committen Sie ihn nicht in die Versionskontrolle und legen Sie seinen Inhalt nicht in eine Umgebungsvariable. Im mutual-Modus identifiziert das konfigurierte Client-Zertifikat diesen mcp-clickhouse-Prozess als CLICKHOUSE_USER. Es authentifiziert keine eingehenden MCP-Clients und gibt deren Identitäten nicht an ClickHouse weiter. Konfigurieren Sie die MCP-Transportauthentifizierung separat.

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

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

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-Transports.

  • CLICKHOUSE_MCP_SERVER_TRANSPORT: Legt die Transportmethode für den MCP-Server fest
    • Standard: "stdio"
    • Gültige Optionen: "stdio", "http", "sse". Dies ist nützlich für die lokale Entwicklung mit Tools wie MCP Inspector.
    • stdio ist typisch für Claude Desktop; http/sse legen einen Netzwerk-Listener frei (Bind-Host/Port unten)
    • "sse" wählt den veralteten eigenständigen HTTP+SSE-Transport aus und protokolliert eine Warnung. Verwenden Sie "http" für Streamable HTTP in neuen Bereitstellungen.
  • CLICKHOUSE_MCP_BIND_HOST: Host, an den der MCP-Server bei Verwendung von HTTP- oder SSE-Transport gebunden wird
    • Standard: "127.0.0.1"
    • Setzen Sie "0.0.0.0", um an alle Netzwerkschnittstellen zu binden (nützlich für Docker oder Fernzugriff)
    • Wird nur verwendet, wenn der Transport "http" oder "sse" ist — nicht verwandt mit CLICKHOUSE_HOST
  • CLICKHOUSE_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 — nicht verwandt mit CLICKHOUSE_PORT
  • CLICKHOUSE_MCP_QUERY_TIMEOUT: Timeout in Sekunden für Abfragetool-Aufrufe
    • Standard: "30"
    • Erhöhen Sie diesen Wert, wenn Sie Query timed out after ...-Fehler bei schweren Abfragen sehen
    • Wenn eine Abfrage ein Timeout erreicht, versucht der Server, sie mit KILL QUERY abzubrechen
    • Sofern CLICKHOUSE_SEND_RECEIVE_TIMEOUT nicht explizit gesetzt ist, ist 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, sodass die Schemaerkennung Abfragen nicht verzögern kann
  • CLICKHOUSE_MCP_AUTH_TOKEN: Statisches Bearer-Token für HTTP/SSE-Transports
    • Standard: Keines
    • Eines von CLICKHOUSE_MCP_AUTH_TOKEN, FASTMCP_SERVER_AUTH oder CLICKHOUSE_MCP_AUTH_DISABLED=true ist erforderlich für HTTP/SSE-Transports
    • Generieren Sie es mit uuidgen oder openssl rand -hex 32
    • Clients müssen dieses Token im Authorization: Bearer <token>-Header senden
  • FASTMCP_SERVER_AUTH: Delegiert die Authentifizierung an einen FastMCP-Auth-Provider
    • Standard: Keiner
    • 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 gesetzt, lädt mcp-clickhouse den Provider aus den vorhandenen FASTMCP_SERVER_AUTH_*-Umgebungsvariablen; lassen Sie CLICKHOUSE_MCP_AUTH_TOKEN in diesem Modus ungesetzt
    • Benutzerdefinierte Provider erhalten keine umgebungsabgeleiteten Konstruktorargumente und müssen eine argumentlose Konstruktion unterstützen
    • FastMCP 4 unterstützt die Supabase-HS256-Verifizierung nicht mehr. Supabase-Bereitstellungen müssen RS256 oder ES256 verwenden.
  • FASTMCP_ENV_FILE: Optionale Datei, die FASTMCP_SERVER_AUTH und providerspezifische Umgebungsvariablen enthält
    • Standard: Keine. Wenn ungesetzt, liest der Kompatibilitätslader fehlende Providerfelder aus .env im Arbeitsverzeichnis. Er liest FASTMCP_SERVER_AUTH nicht aus diesem Fallback
    • Setzen Sie sie vor dem Start in der Prozessumgebung. Ein aus dem Standard-.env geladener Wert kann den Kompatibilitätslader nicht umleiten
    • Wenn prozessgesetzt, kann diese Datei sowohl FASTMCP_SERVER_AUTH- als auch Providerfelder bereitstellen und ersetzt den Arbeitsverzeichnis-Fallback
    • Prozessumgebungswerte haben Vorrang (Groß-/Kleinschreibung wird nicht beachtet)
    • Der mcp-clickhouse-Kompatibilitätslader liest diese Datei nur beim Aufbau der HTTP/SSE-Authentifizierung und liest nur FASTMCP_SERVER_AUTH- und FASTMCP_SERVER_AUTH_*-Einträge. FastMCP 4 kann dieselbe Datei für seine breiteren Einstellungen lesen
    • Das Standard-.env-Laden ist getrennt. Es beginnt im installierten mcp_clickhouse-Paketverzeichnis, löst Symlinks auf, geht nach oben bis zum Dateisystemstamm und lädt die erste gefundene .env oder nichts. Es liest niemals das Arbeitsverzeichnis, unabhängig von der Startmethode. Diese Datei kann FASTMCP_SERVER_AUTH- und Providerfelder zusammen mit anderen Servereinstellungen bereitstellen. Ein Quellcode-Checkout findet normalerweise die .env des Repository-Stamms
  • CLICKHOUSE_MCP_AUTH_DISABLED: Deaktiviert die Authentifizierung für HTTP/SSE-Transports
    • Standard: "false" (Authentifizierung ist aktiviert)
    • Setzen Sie "true", um die Authentifizierung nur für lokale Entwicklung/Tests zu deaktivieren
    • WARNUNG: Nur für die lokale Entwicklung verwenden. Nicht deaktivieren, wenn Netzwerke exponiert sind
  • CLICKHOUSE_MCP_ALLOWED_HOSTS: Durch Kommas getrennte Host-Headerwerte, auf die der HTTP/SSE-Server antwortet
    • Standard für eine Loopback-Bindung: nackte und beliebige-Port-Formen von 127.0.0.1, localhost und [::1]
    • Wenn gesetzt, muss der Wert mindestens einen Host-Eintrag enthalten.
    • Eine konkrete Nicht-Loopback-Bind-Adresse verwendet standardmäßig diese Adresse und den konfigurierten Port. Eine Wildcard-Bindung wie 0.0.0.0 oder :: erfordert einen expliziten nicht-leeren Wert, da der öffentliche Host nicht abgeleitet werden kann.
    • Die Host-Validierung ist eine Verteidigung in der Tiefe gegen DNS-Rebinding. Die Ursprungsvalidierung unten ist von 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 host:*-Form passt nur auf Werte, die einen Port tragen. Ein Host ohne Port (eine Bereitstellung mit Standardport, bei der der Client :80/:443 weglässt) muss auch als nackter exakter Eintrag (example.com) aufgelistet werden.
    • Anfragen mit einem nicht übereinstimmenden oder fehlenden Host-Header erhalten 421 Misdirected Request. GET- und HEAD-Anfragen an /health sind von der Host- und Ursprungsvalidierung ausgenommen, damit Orchestrator-Probes weiterhin funktionieren.
    • Hinter einem Reverse-Proxy bevorzugen Sie die Beibehaltung des ursprünglichen Host-Headers. Sie können stattdessen den Host-Wert des Upstreams auflisten, den der Proxy sendet. Setzen Sie eine explizite Liste, wenn ein Launcher wie fastmcp run die Bind-Adresse für den Fernzugriff überschreibt.
    • mcp-clickhouse erzwingt, dass FastMCPs separate Host- und Origin-Wächter deaktiviert sind. 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 X-Forwarded-*-Header vertrauenswürdig sind
    • Standard: Keine. X-Forwarded-Host wird ignoriert. Die vorhandene Uvicorn-Behandlung von X-Forwarded-For und X-Forwarded-Proto bleibt unverändert.
    • Einträge müssen IP-Adressen oder CIDR-Netzwerke sein, wie 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, bereichsbezogene IPv6-Adressen, *, 0.0.0.0/0 und ::/0 werden ebenfalls abgelehnt.
    • Das Vertrauen basiert auf dem unmittelbaren rohen Socket-Peer. Eine Anfrage von einem anderen Peer oder eine Anfrage ohne Client-Adresse ignoriert X-Forwarded-Host und validiert Host.
    • Ein vertrauenswürdiger Peer darf genau einen X-Forwarded-Host-Header mit genau einem nicht-leeren Wert senden. Doppelte Felder, leere Werte und durch Kommas getrennte Listen erhalten 421 Misdirected Request. Wenn der Header fehlt, wird Host validiert.
    • Verwenden Sie die engstmögliche Adresse oder das engstmögliche Netzwerk. Der MCP-Server muss nur über Proxys in den konfigurierten Bereichen erreichbar sein. Jeder vertrauenswürdige Proxy muss vom Client gelieferte X-Forwarded-Host- und X-Forwarded-Proto-Werte entfernen und überschreiben und X-Forwarded-For aus dem verifizierten Verbindungs-Peer konstruieren.
    • Der integrierte Server und fastmcp run deaktivieren Uvicorns äußere Proxy-Header-Behandlung, validieren den Host vom rohen Peer und wenden dann X-Forwarded-For und X-Forwarded-Proto an. Das explizite Aktivieren von uvicorn_config["proxy_headers"] führt in diesem Modus zu einem Startfehler.
    • Direkte ASGI-Einbettung muss die Proxy-Header-Behandlung im äußeren ASGI-Server deaktivieren und mcp.http_app(raw_client_address_preserved=True) aufrufen. Ohne diese explizite Zusicherung schlägt die App-Konstruktion fehl, wenn vertrauenswürdige Proxys konfiguriert sind.
  • CLICKHOUSE_MCP_ALLOWED_ORIGINS: Durch Kommas getrennte Origin-Headerwerte, die auf HTTP/SSE akzeptiert werden
    • Standard: Keine, was jede Anfrage ablehnt, die einen Origin-Header trägt
    • MCP erfordert die Ursprungsvalidierung für HTTP/SSE-Transportverbindungen. Anfragen ohne Origin werden akzeptiert, da Nicht-Browser-MCP-Clients es normalerweise weglassen. Ein nicht übereinstimmender Origin erhält 403 Forbidden. Der /health-Endpunkt ist wie oben beschrieben ausgenommen.
    • Einträge sind exakt (http://localhost:3000) oder akzeptieren jeden Port (http://localhost:*). Wie bei Hosts passt die beliebige-Port-Form nur auf Origins, die einen Port tragen; ein Standardport-Origin (https://app.example.com) muss exakt aufgelistet werden.
Reverse-Proxy-Host-Behandlung

Bewahren Sie Host wann immer möglich. Dies hält das weitergeleitete Host-Vertrauen 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 X-Forwarded-Host-Vertrauen. Uvicorn kann diesen Headern basierend auf dem Proxy-Peer vertrauen, selbst wenn CLICKHOUSE_MCP_TRUSTED_PROXIES ungesetzt ist.

CLICKHOUSE_MCP_ALLOWED_HOSTS=mcp.example.com

Standard-nginx ändert Host auf den Upstream-Namen für proxierte Anfragen. Es erstellt oder überschreibt X-Forwarded-Host nicht. Wenn das Bewahren von Host nicht möglich ist, überschreiben Sie den weitergeleiteten Header an der vertrauenswürdigen Kante:

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 sicher, wenn 10.20.0.8 die unmittelbare Quelladresse des Proxys ist, der Serverport von anderen Clients isoliert ist und nginx die eingehenden Weiterleitungsheader wie gezeigt überschreibt. Für eine Proxy-Kette muss jeder vertrauenswürdige Hop unverifizierte eingehende Werte verwerfen, bevor er die neuen Weiterleitungsheader konstruiert.

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 gegen IPv4-Einträge abgeglichen. Envoys append_x_forwarded_host hängt an ein vorhandenes X-Forwarded-Host an, anstatt es zu überschreiben, was eine durch Kommas getrennte Liste erzeugt, die abgelehnt wird. Konfigurieren Sie daher den vertrauenswürdigen Hop so, dass er den Header stattdessen überschreibt. Bei Kubernetes mit Source-NAT (z. B. externalTrafficPolicy: Cluster) kann der beobachtete Peer eine Knoten-IP anstelle des Proxy-Pods sein. Vertrauen Sie daher dem Pod- oder Knoten-CIDR je nach Bedarf; ingress-nginx überschreibt sowohl Host als auch X-Forwarded-Host selbst.

Middleware-Variablen

  • MCP_MIDDLEWARE_MODULE: Python-Modulname, der benutzerdefinierte Middleware enthält, die in den MCP-Server injiziert werden soll
    • Standard: Keiner (keine Middleware geladen)
    • Setzen Sie den Modulnamen (ohne .py-Erweiterung) Ihres Middleware-Moduls
    • Das Modul muss eine setup_middleware(mcp)-Funktion bereitstellen
    • Siehe Benutzerdefinierte Middleware für Details und Beispiele

chDB-Variablen

  • CHDB_ENABLED: Aktiviert/deaktiviert die chDB-Funktionalität
    • Standard: "false"
    • Setzen Sie "true", um chDB-Tools zu aktivieren
    • Erfordert die Installation des optionalen Extras: mcp-clickhouse[chdb]
  • CHDB_DATA_PATH: Der Pfad zum chDB-Datenverzeichnis
    • Standard: ":memory:" (In-Memory-Datenbank)
    • Verwenden Sie :memory: für die In-Memory-Datenbank
    • Verwenden Sie einen Dateipfad für die dauerhafte Speicherung (z. B. /path/to/chdb/data)

Häufige Konfigurationsfehler

  • CLICKHOUSE_SECURE vs. MCP / Ingress-TLS – Das Deaktivieren von CLICKHOUSE_SECURE, weil der MCP-Server hinter Kubernetes-Ingress, einem Reverse-Proxy steht oder über einfaches HTTP erreicht wird, deaktiviert nicht das Datenbank-TLS; es ändert nur, wie dieser Prozess sich mit ClickHouse verbindet. Konfigurieren Sie Ingress-TLS getrennt von den Datenbank-Client-Einstellungen.
  • Native-Protokoll-Ports – CLICKHOUSE_PORT muss auf die HTTP-Schnittstelle von ClickHouse abzielen (standardmäßig 8123/8443). Die Ports 9000/9440 sind für das native TCP-Protokoll (clickhouse-client) und funktionieren nicht mit diesem Server.
  • Host-Verwechslung – CLICKHOUSE_HOST ist der Datenbank-Hostname. CLICKHOUSE_MCP_BIND_HOST ist nur die Adresse, auf der der MCP-HTTP/SSE-Server lauscht.

Beispielkonfigurationen

Für 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-Zertifikat-Authentifizierung:

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 ClickHouse X.509-Client-Zertifikat-Authentifizierung:

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 strengen TLS-Server verlangt wird, während ClickHouse die Basis-Authentifizierung 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-beendender Proxy das Client-Zertifikat verlangt und ClickHouse weiterhin die Basis-Authentifizierung verwendet.

Nur für chDB (im Speicher):

# 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 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 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 läuft der Server auf dem konfigurierten Port (Standard: 8000). Zum Beispiel mit der obigen Konfiguration:

  • MCP-Endpunkt: http://localhost:8000/mcp
  • Health-Check: 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 Bind-Host- und Port-Einstellungen werden nur verwendet, wenn der Transport auf „http“ oder „sse“ gesetzt ist.

Tests ausführen

uv sync --all-extras --dev # install dev dependencies
uv run ruff check . # run linting

docker compose up -d test_services # start ClickHouse
uv run pytest -v tests
uv run pytest -v tests/test_tool.py # ClickHouse only
CHDB_ENABLED=true uv run --extra chdb pytest -v tests/test_chdb_tool.py # chDB only

YouTube-Übersicht

YouTube