mcp-clickhousex
MCP ClickHouse Tool
Ein schreibgeschützter Model Context Protocol (MCP) Server für ClickHouse, der Metadaten-Erkennung, Ressourcen, parametrisierte SELECT-Abfragen, SHOW-Introspektion, Abfrageanalyse und Snapshot-Modus für große Ergebnismengen unterstützt, mit profilbasierter Konfiguration und strikter Durchsetzung von No-DML/DDL.
Anforderungen: Python 3.13+, eine laufende ClickHouse-Instanz und Verbindungsdetails über Umgebungsvariablen oder eine Konfigurationsdatei.
Schnellstart
Legen Sie eine DSN fest und starten Sie den Server mit MCP Inspector:
# Option 1: Run directly with uvx (no clone needed)
export MCP_CLICKHOUSE_DSN="http://default:@localhost:8123/default"
npx -y @modelcontextprotocol/inspector uvx mcp-clickhousex# Option 2: Run from source (clone repo, then)
export MCP_CLICKHOUSE_DSN="http://default:@localhost:8123/default"
npx -y @modelcontextprotocol/inspector uv run main.pyRelated MCP server: io.github.Aguantar/clickhouse-dataops-mcp
Konfiguration
Alle Einstellungen verwenden das Präfix MCP_CLICKHOUSE. Flache Umgebungsvariablen (z. B. MCP_CLICKHOUSE_DSN) sind der unkomplizierte Weg, das Standard-Profil zu konfigurieren, wenn Sie eine einzelne Verbindung haben. Für mehrere Profile wird die benutzerspezifische Datei config.json empfohlen.
Einzelne Verbindung: Konfigurieren Sie über Umgebungsvariablen.
# Connection DSN (required).
export MCP_CLICKHOUSE_DSN="http://user:password@host:8123/database"
# Optional description for the default profile (tooling/AI discovery).
export MCP_CLICKHOUSE_DESCRIPTION="Primary cluster"
# Optional max rows per interactive query (default 500; hard ceiling 1000).
export MCP_CLICKHOUSE_QUERY_MAX_ROWS="500"
# Optional interactive query timeout in seconds (default 30; hard ceiling 300).
export MCP_CLICKHOUSE_QUERY_COMMAND_TIMEOUT_SECONDS="30"
# Optional max rows for snapshot queries (default 10000; hard ceiling 50000).
export MCP_CLICKHOUSE_SNAPSHOT_MAX_ROWS="10000"
# Optional snapshot query timeout in seconds (default 120; hard ceiling 300).
export MCP_CLICKHOUSE_SNAPSHOT_COMMAND_TIMEOUT_SECONDS="120"Mehrere Verbindungen: Verwenden Sie die benutzerspezifische Datei config.json (empfohlen). Umgebungsvariablen funktionieren auch über das Präfix MCP_CLICKHOUSE_PROFILES_<NAME>_ (z. B. MCP_CLICKHOUSE_PROFILES_WAREHOUSE_DSN).
Unix-like:
~/.config/mcp-clickhousex/config.jsonWindows:
%USERPROFILE%\.config\mcp-clickhousex\config.json
Beispiel (config.json):
{
"profiles": {
"default": {
"dsn": "http://default:@localhost:8123/default",
"description": "Primary",
"query_max_rows": 500,
"query_command_timeout_seconds": 60,
"snapshot_max_rows": 10000,
"snapshot_command_timeout_seconds": 120
},
"warehouse": {
"dsn": "http://user:pass@warehouse:8123/analytics",
"description": "Warehouse"
}
}
}Sonderzeichen in Anmeldedaten: Wenn der Benutzername oder das Passwort URL-reservierte Zeichen enthält, kodieren Sie diese in der DSN prozentual:
Zeichen | Kodierung |
|
|
|
|
|
|
|
|
|
|
Zum Beispiel werden Benutzername admin@org und Passwort p#ss? zu admin%40org:p%23ss%3F in der DSN: http://admin%40org:p%23ss%3F@host:8123/database.
Werkzeuge
Die Tool-Beschreibungen entsprechen den Docstrings der Tools in server.py, außer dass das Präfix [ClickHouse] hier weggelassen wird (es bleibt in den MCP-exponierten Metadaten erhalten). Der Parametertext entspricht jedem Field(description=…) desselben Tools.
Werkzeug | Beschreibung | Wichtige Parameter |
| Listet konfigurierte Profile auf. Jeder Eintrag enthält Name und optionale Beschreibung. | — |
| Ruft Clustereigenschaften und Ausführungslimits ab. Gibt die ClickHouse-Serverversion sowie die erzwungenen Limits (max. Zeilen, Timeouts) für das Profil zurück. |
|
| Führt schreibgeschütztes SELECT oder WITH … SELECT aus. Eine Anweisung; DML, DDL, SET, SYSTEM und ähnliches werden abgelehnt. Gibt |
|
| Führt eine SHOW-Introspektionsanweisung aus. Eine Anweisung pro Aufruf; INTO OUTFILE wird abgelehnt. Interaktive Zeilenlimits gelten (Standard 500, harte Obergrenze 1 000). Gleiches Timeout wie run_query. |
|
| Führt EXPLAIN für schreibgeschütztes SELECT oder WITH … SELECT aus. Gibt Plan-, Pipeline- und/oder Syntaxtext zurück. Standardtypen: Plan und Pipeline. Verwendet Abfrage-Timeout und optionale Datenbank; keine Max-Zeilen-Obergrenze im Gegensatz zu run_query. |
|
| Listet Datenbanken auf. Zeilen aus system.databases, die für die Verbindung sichtbar sind. |
|
| Listet Tabellen und Ansichten in einer Datenbank auf. Zeilen aus system.tables: name, engine, primary_key, sorting_key, partition_key, total_rows, total_bytes für die Abfrageplanung. |
|
| Listet Spalten für eine Tabelle oder Ansicht auf. Zeilen aus system.columns für die aufgelöste Datenbank und Tabelle. |
|
Ressourcen
Der Server stellt dieselben Discovery- und Metadaten wie die obigen Tools über URI-adressierbare Ressourcen bereit (profil-zuerst-Hierarchie). Die description jeder Ressource entspricht dem jeweiligen Tool (list_profiles, get_cluster_properties, list_databases, list_tables, list_columns), plus Src:-Tags für URI-Pfadparameter. Alle Ressourceninhalte sind JSON (application/json), außer Snapshots, die CSV (text/csv) zurückgeben. Verwenden Sie das Pfadsegment default für das Standardprofil oder die Standarddatenbank.
Die Ressourcenbeschreibungen entsprechen description=… auf @mcp.resource in server.py (gleiche Präfix-Auslassung wie oben).
URI | Beschreibung |
| Listet konfigurierte Profile auf. Jeder Eintrag enthält Name und optionale Beschreibung. |
| Cluster-Eigenschaften und Ausführungslimits abrufen. Gibt die ClickHouse-Serverversion sowie erzwungene Limits (max. Zeilen, Timeouts) für das Profil zurück. Src: profiles. |
| Datenbanken auflisten. Zeilen aus system.databases, die für die Verbindung sichtbar sind. Src: profiles. |
| Tabellen und Ansichten in einer Datenbank auflisten. Zeilen aus system.tables: name, engine, primary_key, sorting_key, partition_key, total_rows, total_bytes für die Abfrageplanung. Src: profiles, dbs. |
| Spalten für eine Tabelle oder Ansicht auflisten. Zeilen aus system.columns für die aufgelöste Datenbank und Tabelle. Src: profiles, dbs, tables. |
| Ein Abfrageergebnis-Snapshot per ID abrufen. Gibt das vollständige Ergebnis als CSV-String zurück (Kopfzeile + Datenzeilen). Einträge verfallen nach 7 Tagen. Src: run_query with snapshot=true. |
Sicherheit
Nur lesender SQL-Zugriff: run_query erlaubt SELECT / WITH … SELECT; run_show erlaubt eine einzelne SHOW-Anweisung pro Aufruf. INTO OUTFILE ist bei run_show nicht erlaubt. Interaktive Abfragen erzwingen eine enge Zeilenbegrenzung (Standard 500, harte Obergrenze 1 000); für größere Exporte verwenden Sie snapshot=true (Standard 10 000, harte Obergrenze 50 000). Parametrisierte Abfragen werden unterstützt, wo der Treiber es erlaubt (%(name)s- oder {name:Type}-Syntax). Verwenden Sie Umgebungsvariablen für Verbindungsdaten – committen Sie niemals Geheimnisse.
MCP-Host-Beispiele
Codeausschnitte für gängige MCP-Clients mit uvx mcp-clickhousex (kein Klonen erforderlich; stellen Sie sicher, dass uv in Ihrem PATH ist). Ersetzen Sie die Verbindungsdetails nach Bedarf.
Cursor
{
"mcpServers": {
"clickhouse": {
"command": "uvx",
"args": ["mcp-clickhousex"],
"env": {
"MCP_CLICKHOUSE_DSN": "http://default:@localhost:8123/default"
}
}
}
}Codex
[mcp_servers.clickhouse]
command = "uvx"
args = ["mcp-clickhousex"]
[mcp_servers.clickhouse.env]
MCP_CLICKHOUSE_DSN = "http://default:@localhost:8123/default"OpenCode
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"clickhouse": {
"type": "local",
"enabled": true,
"command": ["uvx", "mcp-clickhousex"],
"environment": {
"MCP_CLICKHOUSE_DSN": "http://default:@localhost:8123/default"
}
}
}
}Claude Code
{
"mcpServers": {
"clickhouse": {
"command": "uvx",
"args": ["mcp-clickhousex"],
"env": {
"MCP_CLICKHOUSE_DSN": "http://default:@localhost:8123/default"
}
}
}
}Copilot
{
"inputs": [],
"servers": {
"clickhouse": {
"type": "stdio",
"command": "uvx",
"args": ["mcp-clickhousex"],
"env": {
"MCP_CLICKHOUSE_DSN": "http://default:@localhost:8123/default"
}
}
}
}Speicherorte der Konfigurationsdateien: Cursor .cursor/mcp.json, Codex/Copilot/OpenCode variieren je nach Client; siehe die MCP-Dokumentation Ihres Clients.
Tests
Tests erfordern eine laufende ClickHouse-Instanz. Die Testsuite erstellt eine Beispieltabelle in der Standarddatenbank, befüllt sie und löscht sie danach.
# Run all tests (unit + functional + e2e)
uv run pytest tests/ -vDas Test-Framework verwendet MCP_TEST_CLICKHOUSE_DSN, um die ClickHouse-Instanz zu finden. Wenn nicht gesetzt, fällt es auf http://admin:password123@localhost:8123/default zurück. Setzen Sie die Variable, um Tests auf einen anderen Server zu richten, ohne Ihre Produktions-MCP_CLICKHOUSE_DSN zu beeinflussen:
export MCP_TEST_CLICKHOUSE_DSN="http://user:pass@testhost:8123/default"
uv run pytest tests/ -vRoadmap
Derzeit keine geplanten Funktionen. Eröffnen Sie ein Issue, um Verbesserungen vorzuschlagen.
Mitwirken
Eröffnen Sie Issues oder PRs; folgen Sie dem vorhandenen Stil und fügen Sie wo angemessen Tests hinzu.
Lizenz
MIT. Siehe LICENSE.
Available Tools
8 toolsanalyze_queryARead-only
[ClickHouse] Explain read-only SELECT or WITH … SELECT.
Returns plan, pipeline, and/or syntax text. Default types plan and pipeline. Uses query timeout and optional database; no max-rows cap unlike run_query.
Inputs: sql (required), types, profile, database, +1 more. Returns: Structured EXPLAIN text output keyed by explain type.
get_cluster_propertiesARead-only
[ClickHouse] Get cluster properties and execution limits.
Returns ClickHouse server version plus enforced limits (max rows, timeouts) for the profile.
Inputs: profile. Returns: ClickHouse cluster metadata safe to surface to MCP clients.
list_columnsARead-only
[ClickHouse] List columns for a table or view.
Rows from system.columns for the resolved database and table.
Inputs: table (required), profile, database. Returns: Generic tabular result with ordered columns and aligned row values.
list_databasesBRead-only
[ClickHouse] List databases.
Rows from system.databases visible to the connection.
Inputs: profile. Returns: Generic tabular result with ordered columns and aligned row values.
list_profilesARead-only
[ClickHouse] List configured profiles.
Each entry includes name and optional description.
Inputs: no named parameters. Returns: result
list_tablesARead-only
[ClickHouse] List tables and views in a database.
Rows from system.tables: name, engine, primary_key, sorting_key, partition_key, total_rows, total_bytes for query planning.
Inputs: profile, database. Returns: Generic tabular result with ordered columns and aligned row values.
run_queryARead-only
[ClickHouse] Execute read-only SELECT or WITH … SELECT.
One statement; DML, DDL, SET, SYSTEM, and similar are rejected. Max-rows cap; overflow sets truncated and row_limit. Same SQL validation as analyze_query.
Returns {data, row_count} where data is an RFC 4180 CSV string.
Pass snapshot=true to persist the result to disk and receive a
{snapshot_uri, row_count} instead; fetch the CSV via the snapshot
resource URI.
Inputs: sql (required), profile, database, snapshot, +1 more. Returns: result
run_showARead-only
[ClickHouse] Execute SHOW introspection statement.
One statement per call; INTO OUTFILE rejected. Interactive row limits apply (default 500, hard ceiling 1 000). Same timeout as run_query.
Inputs: sql (required), profile, database, parameters. Returns: Result of a SHOW introspection statement (columns + rows + optional truncation).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool has a distinct purpose: listing profiles, cluster properties, running SELECT queries, running SHOW statements, analyzing queries, and listing databases, tables, and columns. No overlap in functionality.
Uses snake_case consistently, but mixes verb prefixes: 'list_', 'get_', 'run_', 'analyze_'. The pattern is somewhat predictable within categories (metadata listing uses 'list_', execution uses 'run_'), but not fully uniform.
8 tools is well-scoped for a read-only ClickHouse client. Covers metadata discovery, query execution, and analysis without unnecessary tools.
Covers essential read-only operations: metadata listing, SELECT, SHOW, and EXPLAIN. Lacks DDL/DML support, but that is intentional. Minor gap: no tool to retrieve table DDL or status.
Maintenance
Related MCP Connectors
MCP server for querying and analyzing data from ad platforms, analytics tools, and spreadsheets
Read-only MCP server for The Quiet Protocol's engines, benchmarks, proof, and business data.
Read-only MCP server for ClassQuill, a tutoring-business-management platform.
Hosted BigQuery MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Related MCP Servers
- AlicenseAqualityDmaintenanceAn MCP server for ClickHouse with enhanced filtering for database and table discovery, supporting LIKE/NOT LIKE patterns and both ClickHouse and chDB tools.3Apache 2.0
- AlicenseAqualityDmaintenanceA DataOps-focused MCP server for ClickHouse that provides query optimization advice, pipeline latency analysis, and data quality monitoring, with read-only safety.832 PyPIMIT
- AlicenseAqualityBmaintenanceA read-only MCP server for exploratory data analysis across PostgreSQL, MySQL, and ClickHouse databases, providing safe, read-only access with comprehensive analysis capabilities.1084 PyPI6MIT
- FlicenseAqualityDmaintenanceRead-only MCP server for ClickHouse that allows listing databases and tables, describing schemas, and running SELECT queries.4-