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.
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.
- 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
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.
One command plus a key — uvx mcp-clickhousex, then supply credentials