ClickHouse MCP Server

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.

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.

Für lokalen stdio-Betrieb uv run --with mcp-clickhouse --python 3.10 mcp-clickhouse im MCP-Client hinterlegen und CLICKHOUSE_HOST, CLICKHOUSE_USER, CLICKHOUSE_PASSWORD sowie bei Bedarf Port/TLS/Rolle als geschützte Umgebungsvariablen setzen. Für HTTP oder SSE zusätzlich eine dokumentierte MCP-Authentifizierung konfigurieren; Schreibzugriff nur nach bewusster Prüfung freischalten.

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

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.

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.

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.

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.