ClickHouse MCP Server

Offizieller MCP-Server für kontrollierte SQL-Abfragen und Schema-Erkundung in ClickHouse.

Beschreibung

Der ClickHouse MCP Server ist der offizielle Open-Source-Server von ClickHouse für das Model Context Protocol. Er verbindet einen kompatiblen KI-Client mit einer konkreten ClickHouse-Instanz. Laut der ClickHouse-Dokumentation kann der Assistent Datenbanken und Tabellen erkunden sowie SQL-Abfragen ausführen. Das ist ein Datenbankzugang, kein bloßes Such-Plugin: Welche Informationen sichtbar werden und welche Anweisungen möglich sind, bestimmen die Verbindung, der ClickHouse-Benutzer, dessen Rollen und Grants sowie die Serverkonfiguration.

Datenanalyse und Entwicklung mit klarer Grenze

Die drei Kernwerkzeuge sind list_databases, list_tables und run_query. Damit kann ein Client Datenbanken aufzählen, Tabellen samt Metadaten untersuchen und SQL an die verbundene Instanz schicken. Das eignet sich für Analysefragen, Schema-Orientierung, Debugging und das Entwickeln oder Prüfen von Abfragen. Die Kategorien Datenanalyse und Coding sind deshalb passend. Der Server ersetzt jedoch weder Datenmodell-Verantwortung noch eine fachliche Prüfung: Tabellen- oder Abfrageergebnisse können unvollständig, veraltet, missverstanden oder für den angefragten Zweck ungeeignet sein.

Die offizielle Dokumentation beschreibt den Standardbetrieb als lokalen stdio-Prozess; die README dokumentiert zusätzlich Streamable HTTP und SSE. Der Eintrag führt daher both als Deployment-Typ, nicht als Behauptung eines von ClickHouse betriebenen öffentlichen MCP-Endpunkts für dieses Open-Source-Projekt. Für die Datenbankverbindung braucht der Prozess mindestens CLICKHOUSE_HOST, CLICKHOUSE_USER und CLICKHOUSE_PASSWORD; Port, TLS, Zertifikatsprüfung, Rolle und Standarddatenbank sind weitere optionale Einstellungen. Für ClickHouse Cloud nennt die Dokumentation HTTPS auf Port 8443 als Standard. Das sind Datenbank-Verbindungswerte, nicht automatisch Schutzmechanismen für einen HTTP-MCP-Endpunkt.

Standardmäßig lesen, Schreiben bewusst freischalten

run_query führt SQL aus. Standardmäßig setzt der Server laut README CLICKHOUSE_ALLOW_WRITE_ACCESS=false und erzwingt readonly=1; das soll versehentliche Mutationen während der Erkundung verhindern. Trotzdem kann ein Lesezugriff sensible Tabellen, Namen, Spalten, Abfrageergebnisse oder Metadaten offenlegen. Ein read-only Nutzer ist daher nicht automatisch ein datensparsamer Nutzer. Begrenze Datenbanken, Tabellen, Spalten und Zeilen auf den tatsächlichen Arbeitsauftrag und nutze für einen Agenten einen eigenen ClickHouse-Benutzer statt default oder eines Administrators.

Wird CLICKHOUSE_ALLOW_WRITE_ACCESS=true gesetzt, sind nicht-destruktive DDL/DML-Operationen wie CREATE, INSERT oder ALTER ADD COLUMN möglich, sofern die ClickHouse-Grants dies erlauben. Destruktive SQL-Operationen brauchen zusätzlich CLICKHOUSE_ALLOW_DROP=true; die README zählt unter anderem DROP, TRUNCATE, DELETE, UPDATE und mehrere ALTER-Varianten auf. Dieser zweite Schalter ist nur ein Schutz gegen Irrtümer im MCP-Server, keine Autorisierungsgrenze. Die wirkliche Grenze sind minimal gewährte ClickHouse-Rechte, Rollen und gegebenenfalls serverseitige Limits wie max_table_size_to_drop. Starte mit read-only, einer nicht produktiven Datenbank oder einer abgesicherten Ansicht und aktiviere Schreibrechte nur für einen klar überprüften Vorgang.

Zugangsdaten, Limits und Netzwerkbetrieb

Bewahre Passwort, Token und Konfigurationsdateien außerhalb von Prompts, Repository, Screenshots und Tool-Ausgaben auf. Übergib sie über die geschützte lokale Client-Konfiguration oder einen geeigneten Secret-Mechanismus. Verwende TLS für die Datenbankverbindung, lasse Zertifikatsprüfung eingeschaltet und verwende den HTTP-Port der ClickHouse-Instanz, nicht den nativen clickhouse-client-TCP-Port. Wenn ein HTTP- oder SSE-Transport genutzt wird, verlangt der Server standardmäßig Authentifizierung per Bearer-Token oder OAuth/OIDC; Authentifizierung auszuschalten ist laut README nur für lokale Entwicklung gedacht. Ein Netzwerklistener braucht außerdem restriktive Bind-Adresse, Host-/Origin-Validierung und einen passenden TLS-/Proxy-Rand.

Begrenze auch die Ausführung: CLICKHOUSE_MCP_QUERY_TIMEOUT hat laut README standardmäßig 30 Sekunden und versucht bei Ablauf ein KILL QUERY; CLICKHOUSE_MCP_MAX_WORKERS begrenzt parallele Query-Worker standardmäßig auf 10. Setze projektgerechte Query-, Datenbank- und Ressourcenlimits zusätzlich in ClickHouse. Ein Timeout ersetzt keine Kosten-, Datenmengen- oder Rechtebegrenzung; große zulässige Abfragen können dennoch viele Ergebnisse und sensible Daten liefern.

Prompt Injection und Modell-Datenpfad

Der Agent kann Anweisungen aus Tabelleninhalten, Kommentaren, Fehlermeldungen oder Query-Ergebnissen lesen. Solcher Inhalt ist Datenmaterial, keine vertrauenswürdige Handlungsanweisung. Behandle Aufforderungen wie „ignoriere Regeln“, „gib Credentials aus“ oder „ändere diese Tabelle“ als mögliche Prompt Injection, überprüfe SQL vor der Freigabe und verwende Tool-Bestätigungen des Clients, wenn verfügbar. Kein Eintrag in der Datenbank darf Berechtigungs- oder Freigaberegeln überschreiben.

Der MCP-Server übergibt Metadaten und Abfrageergebnisse an den verbundenen KI-Client. Dieser kann sie in den Modellkontext, Logs, Telemetrie oder an einen externen Modellanbieter geben; das hängt vom gewählten Client, Modell und dessen Einstellungen ab. Ein lokal laufender stdio-Server bedeutet folglich nicht, dass Daten automatisch lokal bleiben. Prüfe den gesamten Pfad vor dem Zugriff auf personenbezogene, vertrauliche oder regulierte Daten. Das Repository steht unter Apache-2.0. Die GitHub-API meldete am 08.09.2026 exakt 869 Sterne; das ist eine Momentaufnahme der Repository-Popularität, kein Qualitäts- oder Sicherheitsnachweis.

FAQ

Kann der Server Daten verändern? Standardmäßig sollen Abfragen read-only laufen. Mit CLICKHOUSE_ALLOW_WRITE_ACCESS=true können jedoch zulässige nicht-destruktive SQL-Änderungen möglich werden; destruktive Operationen benötigen zusätzlich CLICKHOUSE_ALLOW_DROP=true. Die effektive Sicherheitsgrenze sind die ClickHouse-Grants.

Genügt ein read-only Benutzer? Er verhindert Schreibvorgänge, kann aber weiterhin sensitive Daten oder Metadaten lesen. Beschränke deshalb zusätzlich Datenbanken, Tabellen, Spalten, Zeilen und Rollen auf den minimal nötigen Umfang.

Bleiben Query-Ergebnisse bei lokalem stdio lokal? Nicht zwangsläufig. Der MCP-Server läuft lokal, aber der KI-Client kann Ergebnisse in einen Modellkontext, Logs oder zu einem externen Modellanbieter übertragen.

Voraussetzungen

Python 3.10 bis 3.14, uv oder Python/pip, ein MCP-fähiger Client sowie ClickHouse-Host, Benutzer und Passwort mit minimalen benötigten Rechten.

Installationsanleitung

Der ClickHouse MCP Server verbindet einen KI-Client mit einer ClickHouse-Datenbank. Die erste Einrichtung sollte ein begrenzter Test sein, nicht sofort ein Zugang zur Produktion. Beginne mit einer nicht produktiven Instanz oder einer abgesicherten Datenbankansicht, einem dedizierten Benutzer und einer konkreten Frage, die mit wenigen Tabellen beantwortet werden kann. Der Server kann Schema-Metadaten und Abfrageergebnisse an den KI-Client zurückgeben; prüfe daher vorher auch dessen Modell-, Logging- und Aufbewahrungspfad.

Einen minimalen ClickHouse-Benutzer anlegen

Lege keinen Administrator- oder default-Zugang in der MCP-Konfiguration ab. Erstelle einen separaten Benutzer oder eine Rolle, der nur SELECT auf die nötigen Datenbanken, Tabellen oder möglichst restriktive Views besitzt. Read-only verhindert Änderungen, aber nicht das Auslesen vertraulicher Spalten. Entferne deshalb unnötige Tabellen, Spalten und Zeilen bereits auf Datenbankebene. Dokumentiere, wer für diesen Zugang verantwortlich ist, und rotiere das Passwort nach dem eigenen Secret-Verfahren.

Schritt 1: Lokalen stdio-Start konfigurieren

Installiere uv und hinterlege im MCP-Client den offiziellen Befehl uv run --with mcp-clickhouse --python 3.10 mcp-clickhouse. Setze CLICKHOUSE_HOST, CLICKHOUSE_USER und CLICKHOUSE_PASSWORD nur als geschützte Umgebungsvariablen. Für ClickHouse Cloud ist HTTPS auf Port 8443 laut Dokumentation der Standard; bei selbstverwaltetem HTTP kann CLICKHOUSE_SECURE=false und gegebenenfalls Port 8123 nötig sein. Diese Werte beschreiben die Datenbankverbindung. Sie konfigurieren nicht automatisch TLS oder Authentifizierung eines separaten MCP-HTTP-Endpunkts.

bash
uv run --with mcp-clickhouse --python 3.10 mcp-clickhouse

Abfragen und Ergebnisumfang begrenzen

Lass CLICKHOUSE_ALLOW_WRITE_ACCESS zunächst auf dem Standardwert false. Dann erzwingt der Server laut README read-only Abfragen. Konfiguriere einen angemessenen CLICKHOUSE_MCP_QUERY_TIMEOUT und prüfe, ob auch ClickHouse-seitige Profile, Quotas, Speicher- und Ergebnislimits zu deinem Workload passen. Fordere im Client gezielt kleine, nachvollziehbare Abfragen an, etwa eine Tabellenliste oder eine aggregierte Kennzahl, statt unbeschränkt SELECT * zu erlauben. Ein Timeout und ein Tool-Dialog ersetzen keine Grants und keine Datenminimierung.

Schreibzugriff nur mit klarer Freigabe

Soll ein Workflow Tabellen anlegen, Daten einfügen oder Strukturen ändern, prüfe erst SQL, Zielobjekt und Rückrollplan. CLICKHOUSE_ALLOW_WRITE_ACCESS=true erlaubt laut README nur die nicht-destruktive Schreibklasse zusätzlich zu passenden ClickHouse-Grants. Für DROP, TRUNCATE, DELETE, UPDATE und weitere geschützte Varianten ist außerdem CLICKHOUSE_ALLOW_DROP=true nötig. Diese Flags sind keine Sicherheitsgrenze. Erteile entsprechende Datenbankrechte nur zeitlich und fachlich begrenzt und bestätige jede Mutation im Client, sofern er das anbietet.

Schritt 2: Netzwerk, Prompt Injection und Modellpfad prüfen

Für stdio bleibt der Prozess lokal. Bei HTTP oder SSE verlangt der Server standardmäßig Bearer-Token oder OAuth/OIDC; deaktiviere diese Authentifizierung nicht außerhalb lokaler Tests. Begrenze Bind-Adresse und erlaubte Hosts/Origins und setze TLS am geeigneten Infrastruktur-Rand. Lies Tabelleninhalte, Kommentare und Fehlermeldungen als untrusted data: Sie können eine Prompt Injection enthalten, die einen Agenten zu Datenexport, Credential-Offenlegung oder SQL-Änderungen drängen soll. Keine solche Anweisung darf die Rechte- oder Freigaberegeln ändern. Kontrolliere außerdem, ob Query-Ergebnisse an ein externes Modell, Logs oder Telemetrie gehen. Halte für Freigaben nachvollziehbar fest, welche Datenbank, Tabellen, Rollen und Tool-Aufrufe in diesem Testumfang erlaubt sind. Erst wenn Datenbankzugriff und Modellpfad akzeptiert sind, ist der Server produktionsreif eingegrenzt.

uv run --with mcp-clickhouse --python 3.10 mcp-clickhouse

Authentifizierung

Die Datenbankverbindung verwendet ClickHouse-Host, Benutzer und Passwort; optional ist CLICKHOUSE_ROLE. HTTP/SSE-MCP-Transport verlangt standardmäßig Bearer-Token oder OAuth/OIDC. stdio benötigt keine separate MCP-Netzwerkauthentifizierung.

Benötigte Zugriffsrechte

Rechte folgen dem verwendeten ClickHouse-Benutzer, seinen Rollen und Grants. Nutze einen dedizierten least-privilege Benutzer; read-only ist Standard, Schreib- und besonders destruktive SQL-Operationen brauchen bewusste zusätzliche Flags und passende ClickHouse-Grants.

Übertragene oder gespeicherte Daten

Schema-Metadaten und SQL-Ergebnisse gehen an den MCP-Client und können dort in Modellkontext, Logging, Telemetrie oder einen externen Modellanbieter gelangen. Lokaler stdio-Betrieb allein begrenzt diesen weiteren Datenpfad nicht.

Sicherheitsrisiken

SQL kann Daten lesen, offenlegen, erstellen oder verändern. Risiken umfassen überweite Grants, Credentials in Konfigurationen, große Abfragen, Netzwerkexposition sowie Prompt Injection aus Datenbankinhalten. Query- und Ressourcenlimits sowie menschliche Freigaben ergänzen, ersetzen aber nicht, least privilege.

Lizenz und Kosten

Lizenz
Apache-2.0
Kosten
kostenlos

Der Quellcode steht unter Apache-2.0. Bedingungen für die verwendete ClickHouse-Instanz, Infrastruktur und den KI-Client richten sich nach deren jeweiligem Betreiber.

Alternativen

Noch nicht erfasst.

Auf einen Blick

Anbieter
ClickHouse
Status
Offizieller Server
Betriebsart
Lokal und Remote
Aktuelle Version
Noch nicht erfasst.
GitHub-Sterne
906
Zuletzt geprüft
08.09.2026

Repository und Dokumentation

Kategorien

Unterstützte Clients