mcpField
C
clickhouse-dataops-mcp

clickhouse-dataops-mcp

Local
github.com/AguantarDatabases0Updated 32w ago
Repository

About clickhouse-dataops-mcp

clickhouse-dataops-mcp is a read-only ClickHouse MCP server for DataOps teams, combining query execution with optimization advice, pipeline latency analysis, and data-quality checks. It adds diagnostics and safety controls beyond basic query access.

Key features

  1. 01Run SELECT with partition warnings
  2. 02Analyze queries with EXPLAIN
  3. 03Inspect schemas and table catalog
  4. 04Measure CDC pipeline latency
  5. 05Detect data quality issues
  6. 06Diagnose slow queries and disk usage

Use cases

  1. 01Review query plans and optimization options
  2. 02Monitor CDC segment latency
  3. 03Check tables for nulls, duplicates, and gaps
  4. 04Investigate slow queries and storage use

MCP support

Exposes ClickHouse query and DataOps diagnostic tools to MCP clients. Queries are read-only, with DDL and DML blocked, as well as multi-statement input.

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config
{
  "mcpServers": {
    "aguantar-clickhouse-dataops": {
      "command": "uvx",
      "args": [
        "clickhouse-dataops-mcp"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<CLICKHOUSE_HOST>",
        "CLICKHOUSE_PORT": "<CLICKHOUSE_PORT>",
        "CLICKHOUSE_PASSWORD": "<CLICKHOUSE_PASSWORD>"
      }
    }
  }
}
Run commanduvx clickhouse-dataops-mcp
Environment variables to set
CLICKHOUSE_HOSTClickHouse HTTP host
CLICKHOUSE_PORTClickHouse HTTP port
CLICKHOUSE_PASSWORDSecretClickHouse password

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages
pypiclickhouse-dataops-mcp0.1.1

Tools

No tool list yet

Local servers expose tools only once running on your machine, and the maintainer has not provided a tool list.

Details

From the project README

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

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

VariableDefaultDescription
CLICKHOUSE_HOSTlocalhostClickHouse HTTP host
CLICKHOUSE_PORT8123ClickHouse HTTP port
CLICKHOUSE_USERdefaultClickHouse username
CLICKHOUSE_PASSWORD(empty)ClickHouse password
CLICKHOUSE_DATABASEcdc_pipelineDefault database
CLICKHOUSE_QUERY_TIMEOUT30Query timeout in seconds

License

MIT

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.