analyze_query
[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.
LABSCO SUMMARY
A production cluster you can hand over without holding your breath.
Read-only is enforced by the server, not requested in a prompt: one statement per call, writes and SYSTEM commands refused, rows and seconds capped. What is left is enough to walk the schema, explain a query, run it, and take a large result away as a file.
What it is
A read-only ClickHouse server in Python: metadata discovery, parameterised SELECT, SHOW introspection, EXPLAIN, and a snapshot mode for results too big to hand back inline. Connections are named profiles, so several clusters live behind one server.
What you get
- Databases, tables and columns read from system.databases, system.tables and system.columns — engine, primary key, sorting key, partition key, row and byte totals, the things a query plan turns on
- One read-only SELECT or WITH … SELECT per call, returned as RFC 4180 CSV with a row count; DML, DDL, SET and SYSTEM are rejected
- SHOW introspection as its own tool, one statement per call, with INTO OUTFILE refused
- EXPLAIN before you commit — plan, pipeline and syntax, with no row cap applied
- Snapshot mode for big extracts: pass snapshot=true and the full result is written to disk and returned as a chx:// resource URI, good for 7 days
- Named parameters through the driver's own placeholders, so values are not pasted into the SQL
- The ClickHouse server version and the profile's enforced limits reported on request, so the ceiling is known before a query is written
Requirements
Python 3.13 or newer and a reachable ClickHouse instance. Published to PyPI as mcp-clickhousex and launched over stdio with uvx. A single connection needs only MCP_CLICKHOUSE_DSN — an ordinary ClickHouse URL carrying user, password, host and database, with reserved characters percent-encoded. Limits have their own variables: interactive queries default to 500 rows and 30 seconds, snapshots to 10,000 rows and 120 seconds, with hard ceilings of 1,000, 50,000 and 300 seconds. Several clusters are better kept in ~/.config/mcp-clickhousex/config.json.
Setup effort
One command — uvx mcp-clickhousex
USE CASES
01
Getting oriented in an unfamiliar cluster
List the databases, then the tables with their engines and sorting keys, then the columns of the one that matters — before a line of SQL is written.
02
Answering a question against live data
Run one SELECT with named parameters and read the CSV that comes back; anything that is not a read is refused rather than attempted.
03
Checking a query before it runs for real
Read the plan and the pipeline for the statement, see which indexes it uses, and fix the shape of it while nothing has been scanned.
04
Taking an extract bigger than the interactive cap
Run the same query with snapshot=true — the full result is persisted as CSV and returned as a resource URI you fetch separately.
05
Working across staging and production
List the configured profiles, read the version and limits enforced on the one you mean, then aim each call at it by name.
8 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
get_cluster_properties
[ClickHouse] Get cluster properties and execution limits.
Returns ClickHouse server version plus enforced limits (max rows, timeouts) for the profile.
list_columns
[ClickHouse] List columns for a table or view.
Rows from system.columns for the resolved database and table.
list_databases
[ClickHouse] List databases.
Rows from system.databases visible to the connection.
list_profiles
[ClickHouse] List configured profiles.
Each entry includes name and optional description.
list_tables
[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.
run_query
[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.
run_show
[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.
BEFORE YOU INSTALL
What to know first
Tools you get
8 tools when we connected. Every tool is read-only; run_query rejects DML, DDL, SET and SYSTEM. Queries return at most 500 rows and time out at 30s by default; larger results need snapshot=true.
Requires
uvx on PATH
Where it runs
All 4 documented clients run the server on your machine.
CONTEXT COST
Light Standing cost
Rated by the size of the 8 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
Connect your client
Server setup
TERMINAL
uvx mcp-clickhousexMCP Clients
Cursor
CURSOR · JSON
{
"mcpServers": {
"clickhouse": {
"command": "uvx",
"args": [
"mcp-clickhousex"
],
"env": {
"MCP_CLICKHOUSE_DSN": "http://default:@localhost:8123/default"
}
}
}
}.cursor/mcp.json
OpenCode
OPENCODE · JSON
{
"$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
CLAUDE CODE · JSON
{
"mcpServers": {
"clickhouse": {
"command": "uvx",
"args": [
"mcp-clickhousex"
],
"env": {
"MCP_CLICKHOUSE_DSN": "http://default:@localhost:8123/default"
}
}
}
}GitHub Copilot
GITHUB COPILOT · JSON
{
"inputs": [],
"servers": {
"clickhouse": {
"type": "stdio",
"command": "uvx",
"args": [
"mcp-clickhousex"
],
"env": {
"MCP_CLICKHOUSE_DSN": "http://default:@localhost:8123/default"
}
}
}
}
