ClickHouse MCP server
ClickHouse's official MCP server lets agents list databases and tables and run read-only SQL against a ClickHouse cluster.
The ClickHouse MCP Server is the official server from ClickHouse that gives an AI agent safe, read-only access to a ClickHouse cluster. The agent can enumerate databases, list tables in a database with full metadata, and run SELECT queries that execute inside a read-only session by default, so an over-eager model cannot mutate or drop data unless you explicitly opt in via the CLICKHOUSE_ALLOW_WRITE_ACCESS and CLICKHOUSE_ALLOW_DROP flags. It also bundles chDB, ClickHouse's embedded SQL engine, so when CHDB_ENABLED is set the agent can query local files (Parquet, CSV, URLs) without a server round trip. This makes it a natural fit for analytics work: pointing a coding agent at a warehouse to answer questions, draft dashboards, or explore an unfamiliar schema.
It runs over stdio and is launched with uvx (or installed with pip), authenticating with the CLICKHOUSE_HOST, CLICKHOUSE_USER, and CLICKHOUSE_PASSWORD environment variables, plus optional CLICKHOUSE_PORT, CLICKHOUSE_SECURE, and CLICKHOUSE_DATABASE settings to match your deployment. It works against ClickHouse Cloud and self-hosted clusters alike. Because the safe default is read-only, it is well suited to handing a production warehouse to an agent for exploration without write risk.
Quick install
Copy-paste configs are provided for all 8 supported clients. Pick your client below.
Add to ~/.claude.json
{
"mcpServers": {
"clickhouse": {
"command": "uvx",
"args": [
"--with",
"mcp-clickhouse",
"--python",
"3.10",
"mcp-clickhouse"
],
"env": {
"CLICKHOUSE_HOST": "<CLICKHOUSE_HOST>",
"CLICKHOUSE_USER": "<CLICKHOUSE_USER>",
"CLICKHOUSE_PASSWORD": "<CLICKHOUSE_PASSWORD>"
}
}
}
}claude mcp add clickhouse -- uvx --with mcp-clickhouse --python 3.10 mcp-clickhouseAvailable tools
| Tool | Description |
|---|---|
| list_databases | Lists all databases on the connected ClickHouse cluster. |
| list_tables | Lists the tables in a database, with column and engine metadata and pagination support. |
| run_select_query | Executes a SQL SELECT query against the ClickHouse cluster in a read-only session by default. |
| run_chdb_select_query | Runs a SELECT query through chDB's embedded engine over local files or URLs (requires the chDB extra and CHDB_ENABLED). |
Required configuration
- CLICKHOUSE_HOSTRequired
Hostname of your ClickHouse server.
- CLICKHOUSE_USERRequired
ClickHouse username used to authenticate.
- CLICKHOUSE_PASSWORDRequired
Password for the ClickHouse user.
- CLICKHOUSE_PORTOptional
Server port. Defaults to 8443 with HTTPS or 8123 without.
- CLICKHOUSE_SECUREOptional
Enable HTTPS for the connection. Defaults to true.
- CLICKHOUSE_DATABASEOptional
Default database to connect to.
- CLICKHOUSE_ALLOW_WRITE_ACCESSOptional
Allow DDL/DML writes. Defaults to false (read-only).
- CHDB_ENABLEDOptional
Enable the embedded chDB query engine. Defaults to false.
What you can do with it
Ask questions of a warehouse
Point an agent at a ClickHouse cluster in the default read-only mode and let it list tables and run SELECTs to answer analytics questions without any write risk.
Explore data files locally
With chDB enabled the agent can query Parquet or CSV files directly through run_chdb_select_query, prototyping analysis before anything is loaded into the cluster.
FAQ
- Is it free?
- Yes. mcp-clickhouse is open source under Apache-2.0 and free to run; you only pay for whatever ClickHouse cluster or ClickHouse Cloud service it connects to.
- Does it support remote/OAuth?
- The primary distribution is a local stdio server launched with uvx that authenticates with host, user, and password env vars. It can also run as an HTTP/SSE server guarded by the CLICKHOUSE_MCP_AUTH_TOKEN bearer token, but there is no hosted OAuth endpoint.
- Can the agent modify or drop data?
- No by default. Queries run in a read-only session; you must explicitly set CLICKHOUSE_ALLOW_WRITE_ACCESS (and CLICKHOUSE_ALLOW_DROP for destructive DDL) to enable writes.