ClickHouse maintains an official MCP server that gives an agent read-only SQL access to your cluster — list databases, inspect table schemas, run analytical queries. It also bundles chDB, so the same agent can query a Parquet file or a remote URL without loading anything into ClickHouse first.
Bring your own
Claude Sonnet 4.5
Chat with 60+ AI models on the same workflow — switch to a different model mid-conversation and re-run the same prompt, or use Compare mode to put several side-by-side and balance quality vs. cost.
ClickHouse host, user and password by environment variable. Create a dedicated read-only user scoped to the databases the agent should see.
How models use it and what it is built for.
The server keeps its surface deliberately small: three tools for the cluster and one for chDB. list_databases and list_tables give the model the schema context it needs — including column types, row counts and the table engine, which matters a lot when writing efficient ClickHouse SQL — and run_select_query executes the query. Queries run with readonly enabled by default, so an agent cannot mutate or drop anything even if it decides to try; that default is the single most important thing about deploying this server. The fourth tool, run_chdb_select_query, runs SQL through chDB’s embedded engine, which can read Parquet, CSV and JSON straight off a URL or local path. That turns ad-hoc file analysis into a query rather than an ETL job. Connection is by environment variables and works identically against ClickHouse Cloud and a self-managed cluster.
Typical tools an AI model can call. Exact names vary by version.
Taken from the official ClickHouse documentation — see ClickHouse MCP integrations — official documentation for the full reference.
Environment variables
CLICKHOUSE_HOSTrequiredHostname of the ClickHouse server, e.g. abc123.us-east-1.aws.clickhouse.cloud.
CLICKHOUSE_USERrequiredUsername. Use a dedicated read-only user rather than default.
CLICKHOUSE_PASSWORDrequiredPassword for that user.
CLICKHOUSE_PORTDefaults to 8443 when secure is true, 8123 otherwise.
CLICKHOUSE_SECUREHTTPS on or off. Defaults to true — leave it on for anything remote.
CLICKHOUSE_DATABASEDefault database for queries that do not qualify a table name.
Client configuration
uv / uvx against ClickHouse Cloud
The same configuration works against a self-managed cluster; only the host changes.
{
"mcpServers": {
"clickhouse": {
"command": "uv",
"args": ["run", "--with", "mcp-clickhouse", "--python", "3.13", "mcp-clickhouse"],
"env": {
"CLICKHOUSE_HOST": "abc123.us-east-1.aws.clickhouse.cloud",
"CLICKHOUSE_USER": "readonly_agent",
"CLICKHOUSE_PASSWORD": "YOUR_PASSWORD",
"CLICKHOUSE_SECURE": "true"
}
}
}
}The ClickHouse SQL playground (no account needed)
A public read-only demo instance — the fastest way to see what the server does before pointing it at your own data.
{
"mcpServers": {
"clickhouse": {
"command": "uv",
"args": ["run", "--with", "mcp-clickhouse", "--python", "3.13", "mcp-clickhouse"],
"env": {
"CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
"CLICKHOUSE_USER": "demo",
"CLICKHOUSE_PASSWORD": "",
"CLICKHOUSE_SECURE": "true"
}
}
}
}Copy any of these into MCP Agent Studio after connecting.
What are the top 20 event types by volume in the last 7 days, and how is that trending?
Find the slowest queries in system.query_log and what they have in common.
Break down signups by country and referrer for last month.
Query this Parquet file on S3 and tell me the distribution of the amount column.
This is not a single-model product: you get the same MCP connection with 60+ models (Claude, GPT, Gemini, DeepSeek, open-weight, and more), you can switch mid-conversation, and you can open Compare mode to run the same prompt against multiple models at once. The card above is a suggested starting point for this server — not the only choice.
Default pick for ClickHouse
Claude Sonnet 4.5
ClickHouse SQL rewards knowing the engine and partition key. Sonnet 4.5 reads the schema first and writes queries that use them instead of scanning everything.
Listing tools proves the server is reachable, not that a model can work with it. Evals go further: they read every tool on the server, write a test suite from its real schemas, and run it — code decides pass/fail on the responses (schema conformance, error codes, pagination, result caps) while a scoring model grades plain-English tasks driven through the tools.
Get a pass/fail report per tool with the evidence behind each verdict — and replay the same suite after every schema change. Destructive tools are excluded from the run.
Run evalsOpen MCP Agent Studio with the connection pre-filled. Add your token, pick any of 60+ models, and start chatting — no install required.
Open Agent StudioCommon questions about connecting, scoping and using it safely.
It is the official MCP server from ClickHouse, published as mcp-clickhouse. It exposes database and table discovery plus read-only analytical SQL to an AI agent, and bundles chDB for querying files and URLs directly.
Not with the defaults. Queries execute with the readonly setting enabled, so anything other than a SELECT is rejected by ClickHouse itself. Back that up with a dedicated read-only user and the boundary holds even if the configuration changes.
chDB is ClickHouse as an embedded engine with no server. run_chdb_select_query uses it to run SQL directly over Parquet, CSV or JSON at a local path or remote URL, so an agent can analyse a file without anyone loading it into a table first.
Yes, and that is the common case. Point CLICKHOUSE_HOST at your Cloud hostname with CLICKHOUSE_SECURE set to true. The same server works against a self-managed cluster with no other changes.
Give the agent user a ClickHouse settings profile with max_execution_time, max_result_rows and max_memory_usage set. That is enforced server-side, which is a far stronger guarantee than asking the model to be careful in a prompt.