Skip to main content
Glama
mcp-clickhousex

mcp-clickhousex

MCP ClickHouse Tool

CI PyPI Python 3.13+ License: MIT

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.py

Related 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.json

  • Windows: %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

#

%23

?

%3F

/

%2F

@

%40

%

%25

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

list_profiles

Listet konfigurierte Profile auf. Jeder Eintrag enthält Name und optionale Beschreibung.

—

get_cluster_properties

Ruft Clustereigenschaften und Ausführungslimits ab. Gibt die ClickHouse-Serverversion sowie die erzwungenen Limits (max. Zeilen, Timeouts) für das Profil zurück.

profile — Profilname; verwendet Standardprofil, wenn nicht angegeben. Quelle: profiles.

run_query

Führt schreibgeschütztes SELECT oder WITH … SELECT aus. Eine Anweisung; DML, DDL, SET, SYSTEM und ähnliches werden abgelehnt. Gibt {data, row_count} zurück, wobei data ein RFC 4180 CSV-String ist. Übergeben Sie snapshot=true, um das Ergebnis auf der Festplatte zu speichern und stattdessen {snapshot_uri, row_count} zu erhalten; rufen Sie die CSV über die Snapshot-Ressourcen-URI ab. Max-Zeilen-Limit; bei Überlauf werden truncated und row_limit gesetzt. Gleiche SQL-Validierung wie analyze_query.

sql (erforderlich) — Schreibgeschütztes SELECT oder WITH … SELECT. Eine Anweisung; verwenden Sie qualifizierte db.table oder Datenbank. Treiber-Platzhaltersyntax für Parameter. parameters — Benannte Parameter für Treiber-Platzhalter (z. B. %(name)s oder {name:Type}). database — Standarddatenbank der Sitzung für nicht qualifizierte Namen. Quelle: databases. profile — Profilname; verwendet Standardprofil, wenn nicht angegeben. Quelle: profiles. snapshot — Wenn true, wird das vollständige Ergebnis als CSV-Datei gespeichert und eine Ressourcen-URI (chx://snapshots/{id}) anstelle von Inline-Daten zurückgegeben. Verwenden Sie dies für Abfragen, die das interaktive Zeilenlimit (1 000) überschreiten könnten. Snapshot-Limits gelten (Standard 10 000 Zeilen, harte Obergrenze 50 000). Einträge verfallen nach 7 Tagen.

run_show

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.

sql (erforderlich) — Einzelne SHOW-Anweisung (z. B. SHOW DATABASES, SHOW CREATE TABLE). Kein INTO OUTFILE. parameters — Benannte Parameter für Treiber-Platzhalter (z. B. %(name)s oder {name:Type}). database — Standarddatenbank der Sitzung für nicht qualifizierte Namen. Quelle: databases. profile — Profilname; verwendet Standardprofil, wenn nicht angegeben. Quelle: profiles.

analyze_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.

sql (erforderlich) — Schreibgeschütztes SELECT oder WITH … SELECT für EXPLAIN. Eine Anweisung; gleiche Validierung wie run_query. parameters — Benannte Parameter für Treiber-Platzhalter (z. B. %(name)s oder {name:Type}). database — Standarddatenbank der Sitzung für nicht qualifizierte Namen. Quelle: databases. profile — Profilname; verwendet Standardprofil, wenn nicht angegeben. Quelle: profiles. types — EXPLAIN-Varianten: plan (Indizes), pipeline, syntax. Standard: plan und pipeline, wenn nicht angegeben.

list_databases

Listet Datenbanken auf. Zeilen aus system.databases, die für die Verbindung sichtbar sind.

profile — Profilname; verwendet Standardprofil, wenn nicht angegeben. Quelle: profiles.

list_tables

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.

database — Aufzulistende Datenbank; Client-Standard, wenn nicht angegeben. Quelle: databases. profile — Profilname; verwendet Standardprofil, wenn nicht angegeben. Quelle: profiles.

list_columns

Listet Spalten für eine Tabelle oder Ansicht auf. Zeilen aus system.columns für die aufgelöste Datenbank und Tabelle.

table (erforderlich) — Tabellen- oder Ansichtsname oder database.table. Quelle: tables. database — Datenbank, wenn die Tabelle nicht qualifiziert ist; wird ignoriert, wenn die Tabelle einen Punkt enthält. Client-Standard, wenn nicht angegeben. Quelle: databases. profile — Profilname; verwendet Standardprofil, wenn nicht angegeben. Quelle: profiles.

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

chx://profiles

Listet konfigurierte Profile auf. Jeder Eintrag enthält Name und optionale Beschreibung.

chx://profiles/{profile}/cluster-properties

Cluster-Eigenschaften und Ausführungslimits abrufen. Gibt die ClickHouse-Serverversion sowie erzwungene Limits (max. Zeilen, Timeouts) für das Profil zurück. Src: profiles.

chx://profiles/{profile}/databases

Datenbanken auflisten. Zeilen aus system.databases, die für die Verbindung sichtbar sind. Src: profiles.

chx://profiles/{profile}/databases/{database}/tables

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.

chx://profiles/{profile}/databases/{database}/tables/{table}/columns

Spalten für eine Tabelle oder Ansicht auflisten. Zeilen aus system.columns für die aufgelöste Datenbank und Tabelle. Src: profiles, dbs, tables.

chx://snapshots/{id}

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/ -v

Das 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/ -v

Roadmap

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 tools
analyze_queryA
Read-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_propertiesA
Read-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_columnsA
Read-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_databasesB
Read-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_profilesA
Read-only

[ClickHouse] List configured profiles.

Each entry includes name and optional description.

Inputs: no named parameters. Returns: result

list_tablesA
Read-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_queryA
Read-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_showA
Read-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

    A4/5.0

    Scored across 8 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    8 tools is well-scoped for a read-only ClickHouse client. Covers metadata discovery, query execution, and analysis without unnecessary tools.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      An MCP server for ClickHouse with enhanced filtering for database and table discovery, supporting LIKE/NOT LIKE patterns and both ClickHouse and chDB tools.
      3
      Apache 2.0
    • A
      license
      A
      quality
      D
      maintenance
      A DataOps-focused MCP server for ClickHouse that provides query optimization advice, pipeline latency analysis, and data quality monitoring, with read-only safety.
      8
      32 PyPI
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      A read-only MCP server for exploratory data analysis across PostgreSQL, MySQL, and ClickHouse databases, providing safe, read-only access with comprehensive analysis capabilities.
      10
      84 PyPI
      6
      MIT