ClickHouse MCP Server

offiziell

Fragen Sie Ihren ClickHouse-Datenbankserver ab.

GitHub

808

Dokumentation

ClickHouse MCP Server

Ein MCP-Server für ClickHouse.

Funktionen

ClickHouse-Tools

run_query
- Führt 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ührt SQL-Abfragen mit der eingebetteten ClickHouse-Engine von chDB aus.
- Eingabe: query (String): Die auszuführende SQL-Abfrage.
- Fragt 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 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

Der Endpunkt ist absichtlich nicht authentifiziert, damit Orchestrator-Probes (z. B. Kubernetes-Liveness/Readiness, Load Balancer) ihn ohne Anmeldeinformationen erreichen können. Der Antwort-Body 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 usw.	`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 er das Token in Anfragen einschließt:

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 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 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 hier befindet:
- Unter macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Unter 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 so, dass sie auf Ihren eigenen ClickHouse-Dienst 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, damit bei der Erkundung 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-Erkundung.

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 lieber 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 wie folgt finden:

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 mithilfe des Kontextstatusschlüssels 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.
Für einfaches 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 folgenden Umgebungsvariablen werden verwendet, um die ClickHouse- und chDB-Verbindungen zu konfigurieren:

ClickHouse-Variablen

Erforderliche Variablen

CLICKHOUSE_HOST: Der Hostname Ihres ClickHouse-Servers
CLICKHOUSE_USER: Der Benutzername für die Authentifizierung
CLICKHOUSE_PASSWORD: Das Passwort für die 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 erforderlichen Berechtigungen für seinen Betrieb zu gewähren. Die Verwendung von Standard- oder administrativen Benutzern sollte jederzeit strikt vermieden werden.

Optionale Variablen

CLICKHOUSE_PORT: Die Portnummer Ihres ClickHouse-Servers
- Standard: 8443, wenn HTTPS aktiviert ist, 8123, wenn deaktiviert
- Muss normalerweise nicht gesetzt werden, es sei denn, es wird ein nicht standardmäßiger Port verwendet
CLICKHOUSE_ROLE: Die für die Authentifizierung zu verwendende Rolle
- Standard: Keine
- Setzen Sie dies, wenn Ihr Benutzer eine bestimmte Rolle benötigt
CLICKHOUSE_SECURE: HTTPS-Verbindung aktivieren/deaktivieren
- Standard: "true"
- Auf "false" setzen für ungesicherte Verbindungen
CLICKHOUSE_VERIFY: SSL-Zertifikatsüberprüfung aktivieren/deaktivieren
- Standard: "true"
- Auf "false" setzen, um die Zertifikatsüberprüfung zu deaktivieren (nicht für 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 Standard-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
- Standard: Keine (verwendet den Verbindungs-Hostnamen)
- Dies ist nützlich, wenn Sie sich über Proxys oder Load Balancer verbinden, bei denen der Zertifikats-Hostname vom Verbindungs-Hostnamen abweicht. Wenn gesetzt, wird dieser Hostname sowohl für SNI (Server Name Indication) während des TLS-Handshakes als auch für die Hostnamen-Validierung des Zertifikats verwendet.
CLICKHOUSE_CONNECT_TIMEOUT: Verbindungs-Timeout in Sekunden
- Standard: "30"
- Erhöhen Sie diesen Wert, wenn Verbindungs-Timeouts auftreten
CLICKHOUSE_SEND_RECEIVE_TIMEOUT: Sende-/Empfangs-Timeout in Sekunden
- Standard: "300"
- Erhöhen Sie diesen Wert für lang laufende Abfragen
CLICKHOUSE_DATABASE: Zu verwendende Standarddatenbank
- Standard: Keine (verwendet Server-Standard)
- Setzen Sie dies, um automatisch eine Verbindung zu einer bestimmten Datenbank herzustellen
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.
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
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
CLICKHOUSE_MCP_QUERY_TIMEOUT: Timeout in Sekunden für SELECT-Tools
- 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: Keine
- 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: Keine
- 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 lokale Entwicklung verwenden. Nicht deaktivieren, wenn das System Netzwerken ausgesetzt ist
CLICKHOUSE_ENABLED: ClickHouse-Funktionalität aktivieren/deaktivieren
- Standard: "true"
- Auf "false" setzen, um ClickHouse-Tools zu deaktivieren, wenn nur chDB verwendet wird
CLICKHOUSE_ALLOW_WRITE_ACCESS: Schreiboperationen erlauben (DDL und DML)
- 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

Middleware-Variablen

MCP_MIDDLEWARE_MODULE: Python-Modulname, der benutzerdefinierte Middleware enthält, die in den MCP-Server eingefügt werden soll
- Standard: Keine (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-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 eine In-Memory-Datenbank
- Verwenden Sie einen Dateipfad für persistente Speicherung (z. B. /path/to/chdb/data)

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)

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 des HTTP-Transports 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 Bind-Host 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

ClickHouse MCP Server

Dokumentation

ClickHouse MCP Server

Funktionen

ClickHouse-Tools

chDB-Tools

Health-Check-Endpunkt

Sicherheit

Authentifizierung für HTTP/SSE-Transporte

Einrichten der Authentifizierung

OAuth / OIDC via FastMCP

Entwicklungsmodus (Deaktivieren der Authentifizierung)

Konfiguration

Optionaler Schreibzugriff

Schutz vor destruktiven Operationen

Ausführung ohne uv (mit System-Python)

Benutzerdefinierte Middleware

Verwendung

Beispiel-Middleware

Middleware-Funktionen

Dynamische Client-Konfiguration über Kontextstatus

Entwicklung

Umgebungsvariablen

ClickHouse-Variablen

Erforderliche Variablen

Optionale Variablen

Middleware-Variablen

chDB-Variablen

Beispielkonfigurationen

Tests ausführen

YouTube-Übersicht