What it is
The ClickHouse MCP Server is ClickHouse's open-source server for running SQL against a ClickHouse cluster. It has three main tools: run_query for SQL, list_databases, and list_tables with paginated schema details. run_query also handles DESCRIBE and EXPLAIN ESTIMATE so an agent can check a query's output and estimated reads before running it, and since version 0.7.0 (21 September 2026) it accepts named query parameters. An optional chDB tool runs SQL with ClickHouse's embedded engine on files and URLs.
Install from PyPI (uvx mcp-clickhouse) and set connection details such as CLICKHOUSE_HOST in the environment. It runs over stdio by default, or over HTTP or SSE, where it refuses to start without a bearer token, an OAuth or OIDC provider, or an explicit opt-out.
ClickHouse Cloud customers have a second option: a managed remote server at https://mcp.clickhouse.cloud/mcp with 13 read-only tools, OAuth or API-key sign-in, enabled per service in the Cloud console. The open-source repository has about 890 GitHub stars and an Apache 2.0 licence.
Install
uvx mcp-clickhouseOur review
For analytics work, a small tool set is a strength. The agent lists databases and tables, checks a query with EXPLAIN ESTIMATE to see how many rows and parts it would read, then runs it. Read-only mode is the default and is enforced in ClickHouse itself through readonly=1, not by parsing SQL; enabling writes takes CLICKHOUSE_ALLOW_WRITE_ACCESS, and DROP, TRUNCATE, DELETE and UPDATE need a second flag, CLICKHOUSE_ALLOW_DROP, on top.
The security writing is unusually thorough. HTTP mode refuses to start without authentication. The README warns that a .env file anywhere above the installed package can change auth settings, that read-only users can still cancel other queries running as the same user, and that parameter binding is not a privacy feature because values can still appear in query logs. It says plainly that the destructive-operation check is a guard against accidents and that ClickHouse grants are the real boundary.
The gap is result size. Queries time out after 30 seconds by default, but an open issue reports that a 3-million-row SELECT returned a 231 MiB payload inside that window, enough to swamp any model's context. Until a proposed bound lands, a LIMIT habit, a max_result_rows setting on the database user, or middleware is the fix.
The earlier claim that ClickHouse offers no hosted option no longer holds. ClickHouse Cloud's managed endpoint adds read-only tools for services, backups, ClickPipes and a 31-day organisation cost query, with nothing to install. The open-source server remains the one for self-managed clusters, chDB, or teams that want write access under their own controls.
Where it earns its place
A product analyst at a 50-person e-commerce company on ClickHouse Cloud
Answer ad-hoc questions about orders and funnels without writing SQL
Connect Claude to the read-only server with a dedicated ClickHouse user, let the agent list tables and run EXPLAIN ESTIMATE before each SELECT. The server is free; queries bill against the Cloud service's compute, from about $0.39 per unit-hour on AWS us-east-1 Enterprise.
A data platform engineer running self-managed ClickHouse on Kubernetes
Give several internal agents shared, authenticated access to the warehouse
Run mcp-clickhouse over HTTP with an OIDC provider through FastMCP, keep writes off, and add middleware that sets per-tenant settings. Tenant isolation still has to come from ClickHouse users and roles.
A data scientist working with Parquet files on a laptop
Query local and remote files with SQL without loading a database
Install mcp-clickhouse[chdb] and enable run_chdb_select_query; the embedded engine reads files and URLs directly. No server and no Cloud bill, but chDB queries carry no MCP-side write protection beyond what the engine allows.
Before you commit
- Setup
- uvx mcp-clickhouse with CLICKHOUSE_HOST, CLICKHOUSE_USER and CLICKHOUSE_PASSWORD in the client config; documented for Claude Desktop and other stdio clients. ClickHouse Cloud users can instead enable MCP on a service and point a client at https://mcp.clickhouse.cloud/mcp.
- Integrations
- Three tools (run_query, list_databases, list_tables) plus optional run_chdb_select_query. run_query is read-only unless writes are enabled; FastMCP middleware can intercept calls for logging or per-user settings.
- Data and privacy
- The server can read anything its ClickHouse user is granted, so use a dedicated least-privilege user. It runs on your machine; nothing goes to ClickHouse the company unless your database is on ClickHouse Cloud. Query parameters can appear in ClickHouse query logs.
- Cost at scale
- The server is free. On ClickHouse Cloud Enterprise, compute runs $0.33 to $0.52 per unit-hour (8 GiB, 2 vCPU) and storage $22 to $27.50 per TB-month, depending on region. Agents that scan without EXPLAIN ESTIMATE can wake idle services and burn compute.
- Limits
- Default query timeout 30 seconds and 10 worker threads. No cap on returned rows (issue #223), no admin tools, and no built-in multi-user mode. The hosted Cloud server's billing tool covers at most 31 days per query.
What's good
- Read-only by default, enforced server-side with readonly=1
- Separate opt-in for DROP, TRUNCATE, DELETE and UPDATE
- EXPLAIN ESTIMATE lets agents check cost before running
- HTTP mode requires a token or OAuth/OIDC
What's not
- No bound on result size; large SELECTs can flood context
- Python and uv needed for the self-run server
- No multi-user or tenant isolation beyond ClickHouse grants
- Cloud's hosted server is a separate, read-only product
Best for
Data teams who want an agent to answer questions from ClickHouse with safe defaults.
Alternatives
ClickHouse MCP Server: common questions
- Is ClickHouse MCP Server worth it?
- Three tools and a read-only default make this a safe first database server for an analytics agent, provided you cap result sizes yourself. We rate it 4.2 out of 5.
- How much does ClickHouse MCP Server cost?
- Free and Apache-2.0 licensed. ClickHouse Cloud is billed separately (Enterprise compute from about $0.33 per 8 GiB unit-hour) and offers a 30-day trial with $300 of credits.
- What are the downsides of ClickHouse MCP Server?
- No bound on result size; large SELECTs can flood context; python and uv needed for the self-run server; no multi-user or tenant isolation beyond ClickHouse grants; cloud's hosted server is a separate, read-only product.
- Who is ClickHouse MCP Server best for?
- Data teams who want an agent to answer questions from ClickHouse with safe defaults.
- How much does ClickHouse MCP Server cost for a team or in production?
- The server is free. On ClickHouse Cloud Enterprise, compute runs $0.33 to $0.52 per unit-hour (8 GiB, 2 vCPU) and storage $22 to $27.50 per TB-month, depending on region. Agents that scan without EXPLAIN ESTIMATE can wake idle services and burn compute.
- Is ClickHouse MCP Server safe for company data?
- The server can read anything its ClickHouse user is granted, so use a dedicated least-privilege user. It runs on your machine; nothing goes to ClickHouse the company unless your database is on ClickHouse Cloud. Query parameters can appear in ClickHouse query logs.
- What are the best ClickHouse MCP Server alternatives?
- The closest alternatives we have reviewed are Snowflake-managed MCP Server, MCP Toolbox for Databases and Grafana MCP Server.
Answers checked Oct 23, 2026.
Make ClickHouse MCP Server? Show this rating on your site
