The table listing returns schema, comment, row count and column count together, which is usually enough for the model to write a correct query on the first attempt rather than exploring with SELECT *. The write path is a deliberate switch, and drops need a second one — without them the server answers questions and changes nothing.
ClickHouse's own MCP server: list the databases, list a database's tables with their schema and size, and run SQL. Queries execute read-only unless CLICKHOUSE_ALLOW_WRITE_ACCESS is set.
- The databases on the connected cluster, listed
- Tables in a database with schema, comment, row count and column count, filtered by LIKE or NOT LIKE, paged 50 at a time, and with column metadata droppable for a lighter response
- SQL executed read-only by default; CLICKHOUSE_ALLOW_WRITE_ACCESS=true enables DDL and DML, and CLICKHOUSE_ALLOW_DROP is a second switch for drops and truncates
- A per-query timeout, 30 seconds by default, so a runaway scan fails instead of hanging the session
- A session role activated on connect through CLICKHOUSE_ROLE, so the agent inherits exactly the grants that role carries
- An unauthenticated /health endpoint when it runs over HTTP or SSE, answering 200 only while it can actually reach ClickHouse
- Bearer-token auth on the HTTP transports, or a FastMCP identity provider for a production deployment
Python with uv, a reachable ClickHouse instance, and CLICKHOUSE_HOST, CLICKHOUSE_USER and CLICKHOUSE_PASSWORD. The connection is HTTPS by default, which is why the port defaults to 8443 and drops to 8123 when CLICKHOUSE_SECURE is false. A Docker image is published too.
Build from source — clone the repository and build it, then point your client at the binary