Skip to main content
Glama
Sign In
io.github.Aguantar/clickhouse-dataops-mcp

io.github.Aguantar/clickhouse-dataops-mcp

by Aguantar
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

clickhouse-dataops-mcp

mcp-name: io.github.Aguantar/clickhouse-dataops-mcp

A DataOps-focused MCP server for ClickHouse with query optimization, pipeline latency analysis, and data quality monitoring.

Features

Unlike generic ClickHouse MCP servers that only run queries, this server acts as a query optimization advisor:

  • ch_query — Execute SELECT with automatic partition pruning warnings

  • ch_explain_query — EXPLAIN-based analysis with optimization suggestions

  • ch_table_schema — Comprehensive table metadata (columns, keys, partitions, samples)

  • ch_pipeline_latency — CDC pipeline per-segment latency (p50/p95/p99)

  • ch_data_quality — Null/duplicate/gap detection with market coverage checks

  • ch_slow_queries — Slow query detection with root cause diagnosis

  • ch_disk_usage — Disk analysis with TTL and optimization recommendations

  • ch_list_tables — Table catalog with built-in descriptions

Related MCP server: mcp-clickhouse

Safety

All queries are read-only. DDL/DML operations are blocked at the SQL validation layer:

  • Blocked: DROP, TRUNCATE, DELETE, ALTER, INSERT, UPDATE, CREATE, etc.

  • Multi-statement queries blocked (; separator)

  • Comment-based bypass prevented (comments stripped before validation)

  • System tables restricted to allowlist

  • Query timeout: 30 seconds

  • Row limit enforcement

Installation

pip install clickhouse-dataops-mcp

Usage with Claude Code

Add to your .mcp.json:

{
  "mcpServers": {
    "clickhouse": {
      "command": "clickhouse-mcp-server",
      "env": {
        "CLICKHOUSE_HOST": "localhost",
        "CLICKHOUSE_PORT": "8123",
        "CLICKHOUSE_DATABASE": "cdc_pipeline"
      }
    }
  }
}

Environment Variables

Variable

Default

Description

CLICKHOUSE_HOST

localhost

ClickHouse HTTP host

CLICKHOUSE_PORT

8123

ClickHouse HTTP port

CLICKHOUSE_USER

default

ClickHouse username

CLICKHOUSE_PASSWORD

(empty)

ClickHouse password

CLICKHOUSE_DATABASE

cdc_pipeline

Default database

CLICKHOUSE_QUERY_TIMEOUT

30

Query timeout in seconds

License

MIT

Available Tools

8 tools
ch_data_qualityA

Run data quality checks: nulls, duplicates, gaps, and market coverage.

Checks for a specific date:

  • Null/empty values per column

  • Duplicate rows by primary key

  • Hourly data gaps (missing time windows)

  • Market coverage (are all 5 coins present?)

  • Data freshness

Args: table: Table to check (default: crypto_trades) database: Database name (default: cdc_pipeline) check_date: Date to check in YYYY-MM-DD format (default: today)

Inputs: table, database, check_date. Returns: result

ch_disk_usageA

Analyze disk usage by table and partition with recommendations.

Returns:

  • Total disk usage for the database

  • Per-table breakdown (rows, size, parts, percentage)

  • Per-partition breakdown (top 20 by size)

  • TTL information

  • Recommendations (excessive parts, missing TTL on large tables)

Args: database: Database to analyze (default: cdc_pipeline)

Inputs: database. Returns: result

ch_explain_queryA

Analyze a query's execution plan and suggest optimizations.

Runs EXPLAIN PLAN and EXPLAIN PIPELINE, then provides structured analysis:

  • Whether partition pruning is active

  • Whether sorting keys are utilized

  • Specific optimization suggestions (add time filters, use pre-aggregated tables, etc.)

This is the key differentiator from generic ClickHouse tools — it doesn't just execute queries, it advises on how to write better ones.

Args: sql: The SELECT query to analyze database: Target database (default: cdc_pipeline)

Inputs: sql (required), database. Returns: result

ch_list_tablesA

List all tables with metadata and built-in descriptions.

Returns table name, engine type, partition/sorting keys, row count, disk size, and a human-readable description of each table's purpose. Use this as the starting point to understand what data is available.

Args: database: Database to list (default: cdc_pipeline)

Inputs: database. Returns: result

ch_pipeline_latencyA

Analyze CDC pipeline latency by segment.

Measures latency at each stage of the pipeline:

  • source_to_cdc: Upbit → Debezium/Kafka

  • cdc_to_flink: Kafka → Flink processing

  • flink_to_insert: Flink → ClickHouse write

  • end_to_end: total source_ts → inserted_at

Each segment reports p50, p95, p99, and max latency in milliseconds. Also includes data freshness (seconds behind real-time) and per-market breakdown.

Args: market: Filter by market (e.g., "KRW-BTC"). Empty = all markets period: Time window — "10m", "1h", "6h", or "24h" (default: "1h")

Inputs: market, period. Returns: result

ch_queryA

Execute a read-only SQL query against ClickHouse.

Runs SELECT queries with automatic safety validation (DDL/DML blocked), LIMIT enforcement, and partition pruning analysis. Returns results with a warning if the query doesn't leverage partitioning efficiently.

Args: sql: SELECT query to execute database: Target database (default: cdc_pipeline) max_rows: Maximum rows to return (default: 1000, max: 10000)

Inputs: sql (required), database, max_rows. Returns: result

ch_slow_queriesA

Find slow queries with root cause diagnosis.

Scans system.query_log for queries exceeding the duration threshold, then generates a diagnosis for each:

  • Full scan detection (high read_rows without partition pruning)

  • Memory-intensive query detection

  • Aggregation optimization suggestions (use pre-aggregated tables)

  • Error detection

Args: hours: Look back period in hours (default: 24) min_duration_ms: Minimum query duration to report (default: 1000ms) limit: Maximum number of slow queries to return (default: 20)

Inputs: hours, min_duration_ms, limit. Returns: result

ch_table_schemaA

Get comprehensive table metadata: columns, engine, keys, partitions, and sample data.

Returns column types, partition/sorting/primary keys, TTL settings, row counts, disk usage, partition breakdown, and 5 sample rows. Essential for understanding table structure before writing queries.

Args: table: Table name database: Database name (default: cdc_pipeline)

Inputs: table (required), database. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A4.2/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool has a distinct purpose: data quality checks, disk usage, query analysis, table listing, pipeline latency, query execution, slow query diagnosis, and schema details. No two tools overlap in functionality; descriptions clearly differentiate them.

    Naming Consistency4/5

    All tools share the 'ch_' prefix. Most use a verb_noun pattern (e.g., ch_list_tables, ch_explain_query), but 'ch_query' is just a noun and 'ch_slow_queries' is adjective_noun, causing minor inconsistency. Overall pattern is clear.

    Tool Count5/5

    With 8 tools, the server covers a focused data operations scope without being overloaded. Each tool addresses a specific need, and the count feels well-scoped for managing and optimizing ClickHouse.

    Completeness5/5

    The tool set covers essential dataops tasks: exploring tables, checking schema, running queries, analyzing slow queries, explaining plans, monitoring pipeline latency, checking data quality, and disk usage. No obvious gaps for a read-optimized monitoring tool.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • mcp-clickhouse

      stiproot
      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

    • db-connect-mcp

      yugui923
      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
      67 PyPI
      6
      MIT