ClickHouse

offiziell

Fragen Sie Ihren ClickHouse-Datenbankserver ab.

GitHub

845

Was kann man mit Click House MCP machen?

Nur-Lese-SQL-Abfragen ausführen — Bitten Sie den Assistenten, eine beliebige SELECT-Abfrage gegen Ihren ClickHouse-Cluster mit run_query auszuführen.
Datenbanken und Tabellen auflisten — Erkunden Sie Ihr Schema, indem Sie alle Datenbanken mit list_databases auflisten oder mit list_tables durch Tabellen in einer bestimmten Datenbank blättern.
Dateien und URLs direkt über chDB abfragen — Verwenden Sie run_chdb_select_query, um SQL gegen lokale Dateien oder entfernte Datenquellen auszuführen, ohne sie zuerst in ClickHouse zu laden.
Schreib- und destruktive Operationen steuern — Aktivieren Sie CLICKHOUSE_ALLOW_WRITE_ACCESS für DDL/DML und optional CLICKHOUSE_ALLOW_DROP, um DROP- oder TRUNCATE-Anweisungen während KI-gestützter Sitzungen zu erlauben.

Dokumentation

ClickHouse MCP Server

Ein MCP-Server für ClickHouse.

Funktionen

ClickHouse-Tools

run_query
- Führen Sie SQL-Abfragen auf Ihrem ClickHouse-Cluster aus.
- Eingabe: query (String): Die auszuführende SQL-Abfrage.
- Abfragen werden standardmäßig im schreibgeschützten Modus ausgeführt (CLICKHOUSE_ALLOW_WRITE_ACCESS=false), Schreibvorgänge können jedoch bei Bedarf explizit aktiviert werden.
list_databases
- Listet alle Datenbanken auf Ihrem ClickHouse-Cluster auf.
list_tables
- Listet Tabellen in einer Datenbank mit Paginierung auf.
- Erforderliche Eingabe: database (String).
- Optionale Eingaben:
  - like / not_like (String): Wendet LIKE- oder NOT LIKE-Filter auf Tabellennamen an.
  - page_token (String): Token, das von einem vorherigen Aufruf zurückgegeben wurde, um die nächste Seite abzurufen.
  - page_size (int, Standard 50): Anzahl der pro Seite zurückgegebenen Tabellen.
  - 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: Übergeben Sie diesen Wert 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.

chDB-Tools

run_chdb_select_query
- Führen Sie SQL-Abfragen mit der eingebetteten ClickHouse-Engine von chDB aus.
- Eingabe: query (String): Die auszuführende SQL-Abfrage.
- Fragen Sie Daten direkt aus verschiedenen Quellen (Dateien, URLs, Datenbanken) ohne ETL-Prozesse ab.
- 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 (Body: OK) zurück, wenn der Server fehlerfrei 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

Der Endpunkt ist absichtlich nicht authentifiziert, damit Orchestrator-Probes (z. B. Kubernetes-Liveness/Readiness, Load Balancer) ihn ohne Anmeldeinformationen erreichen können. Der Antworttext ist bewusst minimal gehalten, um die Weitergabe 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-Transporte

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

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

Modus	Wann zu verwenden	Umgebungsvariable
Statisches Bearer-Token	Einfache Bereitstellungen, interne Dienste	`CLICKHOUSE_MCP_AUTH_TOKEN`
OAuth / OIDC (via FastMCP)	Azure Entra, Google, GitHub, WorkOS, etc.	`FASTMCP_SERVER_AUTH=<provider-class-path>` (+ anbieterspezifische `FASTMCP_SERVER_AUTH_*`-Variablen)
Deaktiviert	Nur lokale Entwicklung	`CLICKHOUSE_MCP_AUTH_DISABLED=true`

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

Einrichten der Authentifizierung

Generieren Sie ein sicheres Token (kann eine beliebige zufällige Zeichenfolge sein):
```
# Using uuidgen (macOS/Linux)
uuidgen

# Using openssl
openssl rand -hex 32
```

Konfigurieren Sie den Server mit dem Token:

export CLICKHOUSE_MCP_AUTH_TOKEN="your-generated-token"

Konfigurieren Sie Ihren MCP-Client so, dass das Token in Anfragen enthalten ist:

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, rufen Sie den MCP-Endpunkt selbst auf, z. B. mit dem MCP Inspector, oder indem Sie eine JSON-RPC-Anfrage an /mcp mit und ohne den Authorization-Header senden und bestätigen, dass der nicht authentifizierte Aufruf 401 zurückgibt.

OAuth / OIDC via FastMCP

Für Produktionsbereitstellungen mit Identitätsanbietern (Azure Entra, Google, GitHub, WorkOS, etc.) delegieren Sie die Authentifizierung an die integrierten Auth-Provider von FastMCP, anstatt ein statisches Token zu verwenden. Setzen Sie FASTMCP_SERVER_AUTH auf den vollständigen Klassenpfad eines FastMCP-Auth-Providers, zusammen mit den anbieterspezifischen FASTMCP_SERVER_AUTH_*-Variablen, und lassen Sie CLICKHOUSE_MCP_AUTH_TOKEN nicht gesetzt.

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

Siehe die FastMCP-Dokumentation für die vollständige Liste der Anbieter und deren erforderliche Umgebungsvariablen.

Entwicklungsmodus (Deaktivieren der Authentifizierung)

Nur für die lokale Entwicklung und zum Testen können Sie die Authentifizierung deaktivieren, indem Sie Folgendes setzen:

export CLICKHOUSE_MCP_AUTH_DISABLED=true

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 eine oder beide Optionen aktivieren.

Öffnen Sie die Claude Desktop-Konfigurationsdatei, die sich befindet unter:
- Auf macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Auf Windows: %APPDATA%/Claude/claude_desktop_config.json
Fügen Sie Folgendes hinzu:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.10",
        "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",
        "CLICKHOUSE_SEND_RECEIVE_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.10",
        "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",
        "CLICKHOUSE_SEND_RECEIVE_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.10",
        "mcp-clickhouse"
      ],
      "env": {
        "CHDB_ENABLED": "true",
        "CLICKHOUSE_ENABLED": "false",
        "CHDB_DATA_PATH": "/path/to/chdb/data"
      }
    }
  }
}

Sie können auch sowohl ClickHouse als auch chDB gleichzeitig aktivieren:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse[chdb]",
        "--python",
        "3.10",
        "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",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30",
        "CHDB_ENABLED": "true",
        "CHDB_DATA_PATH": "/path/to/chdb/data"
      }
    }
  }
}

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 finden.
Starten Sie Claude Desktop neu, um die Änderungen zu übernehmen.

Optionaler Schreibzugriff

Standardmäßig erzwingt dieser MCP schreibgeschützte Abfragen, sodass während der Exploration keine versehentlichen Mutationen auftreten können. Um DDL- oder INSERT/UPDATE-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 (DROP TABLE, DROP DATABASE, DROP VIEW, DROP DICTIONARY, TRUNCATE TABLE) aus Sicherheitsgründen ein zusätzliches Opt-in-Flag. Dies verhindert versehentliche Datenlöschungen während der KI-Exploration.

Um destruktive Operationen zu aktivieren, setzen Sie beide Flags:

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

Dieser zweistufige Ansatz stellt sicher, dass versehentliche Löschungen sehr schwierig sind:

Schreiboperationen (INSERT, UPDATE, CREATE) erfordern CLICKHOUSE_ALLOW_WRITE_ACCESS=true
Destruktive Operationen (DROP, TRUNCATE) erfordern zusätzlich CLICKHOUSE_ALLOW_DROP=true

Ausführung 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:

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

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",
        "CLICKHOUSE_SEND_RECEIVE_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",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
      }
    }
  }
}

Hinweis: Stellen Sie sicher, dass Sie den vollständigen Pfad zur ausführbaren Python-Datei oder zum mcp-clickhouse-Skript verwenden, wenn diese sich nicht in Ihrem System-PATH befinden. Sie können die Pfade finden mit:

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, Ressourcen-Lesevorgänge, Prompts usw.) abfangen und verarbeiten können.

Verwendung

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())

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.10", "mcp-clickhouse"],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "MCP_MIDDLEWARE_MODULE": "my_middleware"
      }
    }
  }
}

Stellen Sie sicher, dass sich Ihr Middleware-Modul im Importpfad von Python 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:

Protokollierung aller MCP-Anfragen
Spezifische Protokollierung von Tool-Aufrufen
Messung der Anfrageverarbeitungszeit

So verwenden Sie das Beispiel:

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

Middleware-Funktionen

Die Basisklasse Middleware 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 erhält 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 mit dem Kontextstatusschlüssel CLIENT_CONFIG_OVERRIDES_KEY überschreiben. Der Server führt diese Überschreibungen mit der Basiskonfiguration aus Umgebungsvariablen zusammen.

from fastmcp.server.dependencies import get_context
from mcp_clickhouse.mcp_server import CLIENT_CONFIG_OVERRIDES_KEY

ctx = get_context()
ctx.set_state(CLIENT_CONFIG_OVERRIDES_KEY, {
    "connect_timeout": 60,
    "send_receive_timeout": 120
})

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

Entwicklung

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

Hinweis: Die Verwendung des Benutzers default in diesem Zusammenhang ist ausschließlich für lokale Entwicklungszwecke vorgesehen.

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

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.
Zum einfachen Testen mit dem MCP Inspector führen Sie fastmcp dev mcp_clickhouse/mcp_server.py aus, um den MCP-Server zu starten.

Zum Testen mit HTTP-Transport und dem Health-Check-Endpunkt:

# For development, disable authentication
CLICKHOUSE_MCP_SERVER_TRANSPORT=http CLICKHOUSE_MCP_AUTH_DISABLED=true 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

Umgebungsvariablen

Die Konfiguration ist in unabhängige Gruppen unterteilt. Das Vermischen dieser Gruppen ist eine häufige Ursache für schwer zu debuggende Verbindungsfehler:

Gruppe	Variablen	Steuert
ClickHouse-Datenbankverbindung	`CLICKHOUSE_HOST`, `CLICKHOUSE_PORT`, `CLICKHOUSE_SECURE`, `CLICKHOUSE_VERIFY`, …	Wie dieser MCP-Server über die HTTP-Schnittstelle eine Verbindung zu Ihrem ClickHouse-Cluster herstellt
MCP-Server / Transport	`CLICKHOUSE_MCP_`, `FASTMCP_SERVER_AUTH`, `FASTMCP_SERVER_AUTH_`	MCP-Transport, Authentifizierung und Ausführungslimits für Abfragetools
Middleware / chDB	`MCP_MIDDLEWARE_MODULE`, `CHDB_*`	Optionale Erweiterungen

[!WICHTIG] Variablen wie CLICKHOUSE_SECURE, CLICKHOUSE_VERIFY und CLICKHOUSE_PORT gelten nur für die ClickHouse-Datenbankverbindung. Sie konfigurieren nicht TLS, Ports oder Authentifizierung für den MCP-Protokollendpunkt.

Beispiel: Wenn der MCP-Server in Kubernetes hinter einem Ingress ausgeführt wird, der TLS terminiert, ist dies ein Anliegen des MCP-Transports. Halten Sie CLICKHOUSE_SECURE darauf abgestimmt, wie der Pod ClickHouse selbst erreicht (HTTPS → true, einfaches HTTP → false). Das Setzen von CLICKHOUSE_SECURE=false, weil sich der MCP-Server hinter einem Ingress befindet, führt dazu, dass der Server ClickHouse über HTTP anwählt – oft an einem HTTPS-only-Port – und undurchsichtige HTTP/TLS-Fehler in den Serverprotokollen erzeugt.

ClickHouse-Datenbankverbindung

Diese Variablen konfigurieren den clickhouse-connect HTTP-Client und das Verhalten von ClickHouse-gestützten Werkzeugen wie run_query, list_databases und list_tables.

Erforderliche Variablen

CLICKHOUSE_HOST: Der Hostname Ihres ClickHouse-Servers (Datenbank-Endpunkt, nicht die MCP-Server-Bindungsadresse)
CLICKHOUSE_USER: Der Benutzername für die ClickHouse-Authentifizierung
CLICKHOUSE_PASSWORD: Das Passwort für die ClickHouse-Authentifizierung

[!CAUTION] Es ist wichtig, Ihren MCP-Datenbankbenutzer wie jeden anderen externen Client zu behandeln, der sich mit Ihrer Datenbank verbindet, und ihm nur die minimal notwendigen Berechtigungen für seinen Betrieb zu gewähren. Die Verwendung von Standard- oder administrativen Benutzern sollte grundsätzlich 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, es wird ein nicht standardmäßiger Port verwendet
- Muss ein HTTP-Schnittstellenport sein, nicht der native TCP-Protokollport, der von clickhouse-client verwendet wird
- Übliche Werte:
  - HTTP: 8123 (plain) / 8443 (TLS) — verwendet von diesem Server und ClickHouse Cloud HTTPS
  - Natives TCP (hier nicht unterstützt): 9000 (plain) / 9440 (TLS) — verwendet von clickhouse-client
- Wenn der Server mit Port 9000 is for clickhouse-client program antwortet, sind Sie auf das native Protokoll verwiesen; wechseln Sie zum HTTP-Port (8123/8443 oder die HTTP-Zuordnung Ihrer Bereitstellung)
CLICKHOUSE_ROLE: Die für die Authentifizierung zu verwendende ClickHouse-Rolle
- Standard: Keine
- Setzen Sie dies, 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 auf "false" setzen, 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-Datenbankendpunkt – selbst wenn der MCP-Server selbst über HTTP, stdio oder einen Ingress bereitgestellt wird, der TLS separat terminiert
- Dieses Flag nicht mit dem Datenbankport abzustimmen (z. B. CLICKHOUSE_SECURE=false gegen Port 8443) ist ein häufiger Einrichtungsfehler und äußert sich meist in verwirrenden HTTP-Client-Fehlern statt einer klaren „falsches Schema“-Meldung
CLICKHOUSE_VERIFY: SSL-Zertifikatsüberprüfung für die ClickHouse-HTTPS-Verbindung aktivieren/deaktivieren
- Standard: "true"
- Auf "false" setzen, um die Zertifikatsüberprüfung zu deaktivieren (nicht für die Produktion empfohlen)
- TLS-Zertifikate: Das Paket verwendet den Vertrauensspeicher Ihres Betriebssystems für die TLS-Zertifikatsüberprüfung über truststore. Wir rufen truststore.inject_into_ssl() beim Start auf, um eine ordnungsgemäße Zertifikatsbehandlung sicherzustellen. Das standardmäßige SSL-Verhalten von Python wird nur als Fallback verwendet, wenn ein unerwarteter Fehler auftritt.
CLICKHOUSE_SERVER_HOST_NAME: Server-Hostname für SNI-Override und Zertifikatsvalidierung bei der ClickHouse-Verbindung
- Standard: Keine (verwendet den Verbindungshostnamen)
- Dies ist nützlich, wenn die Verbindung über Proxys oder Load Balancer erfolgt, 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 Hostnamenvalidierung des Zertifikats verwendet.
CLICKHOUSE_PROXY_PATH: URL-Pfadpräfix für den ClickHouse-HTTP-Endpunkt
- Standard: Keines
- Setzen Sie dies, wenn die ClickHouse-HTTP-Schnittstelle hinter einem Reverse-Proxy unter einem Pfadpräfix bereitgestellt wird (z. B. /clickhouse)
CLICKHOUSE_CONNECT_TIMEOUT: Verbindungstimeout in Sekunden für den ClickHouse-Client
- Standard: "30"
- Erhöhen Sie diesen Wert, wenn Verbindungstimeouts auftreten
CLICKHOUSE_SEND_RECEIVE_TIMEOUT: Sende-/Empfangstimeout in Sekunden für den ClickHouse-Client
- Standard: "300"
- Erhöhen Sie diesen Wert für lang laufende Abfragen
CLICKHOUSE_DATABASE: Standardmäßig zu verwendende ClickHouse-Datenbank
- Standard: Keine (verwendet Serverstandard)
- Setzen Sie dies, um automatisch eine Verbindung zu einer bestimmten Datenbank herzustellen
CLICKHOUSE_ENABLED: ClickHouse-Datenbankwerkzeuge aktivieren/deaktivieren
- Standard: "true"
- Auf "false" setzen, um ClickHouse-Werkzeuge zu deaktivieren, wenn nur chDB verwendet wird
CLICKHOUSE_ALLOW_WRITE_ACCESS: Schreiboperationen (DDL und DML) gegen ClickHouse erlauben
- Standard: "false"
- Auf "true" setzen, um DDL- (CREATE, ALTER, DROP) und DML-Operationen (INSERT, UPDATE, DELETE) zu erlauben
- Wenn deaktiviert (Standard), werden Abfragen mit der Einstellung readonly=1 ausgeführt, um Datenänderungen zu verhindern
CLICKHOUSE_ALLOW_DROP: Destruktive Operationen erlauben (DROP TABLE, DROP DATABASE, DROP VIEW, DROP DICTIONARY, TRUNCATE TABLE)
- Standard: "false"
- Wirkt nur, wenn CLICKHOUSE_ALLOW_WRITE_ACCESS=true ebenfalls gesetzt ist
- Auf "true" setzen, um destruktive DROP- und TRUNCATE-Operationen explizit zu erlauben
- Dies ist eine Sicherheitsfunktion, um versehentliche Datenlöschung während der KI-Erkundung zu verhindern

MCP-Server und Transport

Diese Variablen steuern den MCP-Prozess selbst, einschließlich Transport, Authentifizierung und Ausführungslimits für Abfragewerkzeuge. Sie sind unabhängig von den obigen 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 nützlich für die lokale Entwicklung mit Werkzeugen wie MCP Inspector.
- stdio ist typisch für Claude Desktop; http/sse stellen einen Netzwerk-Listener bereit (Bindungshost/-port unten)
CLICKHOUSE_MCP_BIND_HOST: Host, an den der MCP-Server gebunden wird, wenn HTTP- oder SSE-Transport verwendet wird
- Standard: "127.0.0.1"
- Auf "0.0.0.0" setzen, um an alle Netzwerkschnittstellen zu binden (nützlich für Docker oder Fernzugriff)
- Wird nur verwendet, wenn der Transport "http" oder "sse" ist – nicht verwandt mit CLICKHOUSE_HOST
CLICKHOUSE_MCP_BIND_PORT: Port, an den der MCP-Server gebunden wird, wenn HTTP- oder SSE-Transport verwendet 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 Abfragewerkzeuge
- Standard: "30"
- Erhöhen Sie dies, wenn Sie Query timed out after ...-Fehler bei umfangreichen Abfragen sehen
CLICKHOUSE_MCP_AUTH_TOKEN: Statisches Bearer-Token für HTTP/SSE-Transporte
- Standard: Keines
- Eines von CLICKHOUSE_MCP_AUTH_TOKEN, FASTMCP_SERVER_AUTH oder CLICKHOUSE_MCP_AUTH_DISABLED=true ist erforderlich für HTTP/SSE-Transporte
- Generieren mit uuidgen oder openssl rand -hex 32
- Clients müssen dieses Token im Authorization: Bearer <token>-Header senden
FASTMCP_SERVER_AUTH: Authentifizierung an einen FastMCP-Auth-Provider delegieren
- Standard: Keiner
- 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 FastMCP den Provider automatisch aus seinen eigenen FASTMCP_SERVER_AUTH_*-Umgebungsvariablen; lassen Sie CLICKHOUSE_MCP_AUTH_TOKEN in diesem Modus ungesetzt
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/Tests zu deaktivieren
- WARNUNG: Nur für die lokale Entwicklung verwenden. Nicht deaktivieren, wenn das System Netzwerken ausgesetzt ist

Middleware-Variablen

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

chDB-Variablen

CHDB_ENABLED: chDB-Funktionalität aktivieren/deaktivieren
- Standard: "false"
- Auf "true" setzen, um chDB-Werkzeuge 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 eine In-Memory-Datenbank
- Verwenden Sie einen Dateipfad für persistente Speicherung (z. B. /path/to/chdb/data)

Häufige Konfigurationsfallen

CLICKHOUSE_SECURE vs. MCP / Ingress-TLS — Das Ausschalten von CLICKHOUSE_SECURE, weil der MCP-Server hinter Kubernetes-Ingress, einem Reverse-Proxy sitzt oder über einfaches HTTP erreicht wird, deaktiviert nicht das Datenbank-TLS; es ändert nur, wie dieser Prozess eine Verbindung zu ClickHouse herstellt. Konfigurieren Sie Ingress-TLS getrennt von den Datenbankclient-Einstellungen.
Native Protokollports — 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 mit diesem Server nicht.
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 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)

Nur für chDB (In-Memory):

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

Für chDB mit persistenter Speicherung:

# 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)

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!

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

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

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

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.10",
        "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 Bindungshost und -port 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