mcp-clickhouse

Ein Model Context Protocol-Server für ClickHouse. Er ermöglicht einem MCP-fähigen Client (Claude Desktop, Claude Code usw.), Schemas zu erkunden, analytische Abfragen auszuführen und die Datenbank zu verwalten – wobei das Verhalten vollständig über Flags gesteuert wird.

Das Sicherheitsmodell ist anweisungsbewusst: Jede SQL-Anweisung wird als lesend, schreibend oder destruktiv klassifiziert und anhand des aktuellen Zugriffsmodus freigeschaltet. Im Nur-Lese-Modus werden Abfragen zusätzlich mit der eigenen readonly=1-Einstellung von ClickHouse ausgeführt.

Funktionen

• Erkundung und Überwachung – Datenbanken, Tabellen, Spalten, SHOW CREATE, Tabellenstatistiken (Teile/Zeilen/Bytes), laufende Abfragen, Servermetriken, Cluster-Topologie.

• Leseabfragen – ein query-Tool, das nur Leseanweisungen akzeptiert und auf CLICKHOUSE_MAX_ROWS begrenzt ist.

• Verwaltung – ein execute-Tool für INSERT/CREATE/ALTER (Lesen/Schreiben) und DROP/TRUNCATE/DELETE (Admin), jeweils durch die Klassifizierung freigeschaltet.

• Zugriffsmodi – read-only → read-write → admin, abgestuft, sodass ein Modus nie Anweisungen oberhalb seiner Stufe freigibt.

• Sicherheitsflags – Datenbank-Allowlist, geschützte Datenbanken, Freigabesteuerung für destruktive Anweisungen, Zeilenlimit, Dry-Run und JSON-Audit-Log (siehe unten).

Related MCP server: clickhouse-mcp-server

Sicherheitsmodell

Die Anweisungsklassifizierung liegt in src/sql.ts und ist ausfallsicher: ALTER … DELETE/UPDATE zählt als destruktiv, und alles, was nicht geparst werden kann, wird als destruktiv behandelt.

Tools

Lesen (read-only+): list_databases, list_tables, describe_table, show_create_table, table_stats, running_queries, server_metrics, cluster_info, query

Schreiben/Admin (read-write+): execute – führt eine einzelne Anweisung nach der Klassifizierung aus; Schreibzugriffe benötigen den Modus read-write, destruktive Anweisungen den Admin-Modus + CLICKHOUSE_ALLOW_DELETE.

Verwendung mit Ihrem MCP-Client

Funktioniert mit Claude Code, Claude Desktop, Cursor, OpenAI Codex CLI, Windsurf, VS Code (Copilot) und jedem anderen MCP-Client – die Einrichtung pro Client finden Sie in docs/CLIENTS.md.

Installation

npm install
npm run build

Ausführen mit Claude Desktop / Claude Code

{
  "mcpServers": {
    "clickhouse": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-clickhouse/dist/index.js"],
      "env": {
        "CLICKHOUSE_URL": "http://clickhouse:8123",
        "CLICKHOUSE_USER": "readonly",
        "CLICKHOUSE_PASSWORD": "…",
        "CLICKHOUSE_MODE": "read-only",
        "CLICKHOUSE_DATABASE_ALLOWLIST": "analytics"
      }
    }
  }
}

Beispiel-Prompts

• „Welche sind die größten Tabellen in der Datenbank analytics?“

• „Zeig mir das Schema für events und führe für diese Woche eine Abfrage mit den täglichen Zählwerten aus.“

• „Welche Abfragen laufen gerade und verbrauchen am meisten Speicher?“

Entwickeln

npm run dev
npm test          # SQL classification + security policy (30 tests)
npm run typecheck

Veröffentlichung

Dieser Server enthält eine server.json für die offizielle MCP-Registry und einen mcpName zur Validierung der npm-Inhaberschaft. Siehe PUBLISHING.md für die Veröffentlichung auf npm und die Auflistung in der MCP-Registry, bei Smithery, Glama, Cursor und PulseMCP.

Lizenz

MIT