ClickHouse

ClickHouse

This connector runs read-only SQL against a ClickHouse server through its HTTP interface: ClickHouse Cloud services and self-hosted servers alike. Every request carries the setting readonly=1, so ClickHouse itself refuses writes, DDL and SET statements, whatever the user's grants. To manage ClickHouse Cloud services (start, stop, scaling, backups, costs) install the ClickHouse Cloud connector.

Setup (3 minutes)

1. CLICKHOUSE_URL: the HTTPS address with port. ClickHouse Cloud: open the service, click Connect, choose HTTPS and copy the host, e.g. https://abc123xyz.europe-west4.gcp.clickhouse.cloud:8443. Self-hosted: https://your-host:8443 (or http://your-host:8123 on a private network).
2. Create a dedicated user that may only read, for example CREATE USER mcp_reader IDENTIFIED BY '...'; GRANT SELECT ON analytics.* TO mcp_reader; plus GRANT SELECT ON system.parts, system.processes, system.query_log TO mcp_reader if you want clickhouse_table_sizes, clickhouse_running_queries and clickhouse_recent_queries. Do not give it a readonly = 2 settings profile: the connector sets readonly=1 and ClickHouse rejects that change under readonly = 2 (readonly = 0 or 1 both work).
3. Put the user name into CLICKHOUSE_USER and its password into CLICKHOUSE_PASSWORD (sent as HTTP Basic auth).
4. ClickHouse Cloud only: the service's IP access list must allow the address AnythingMCP calls from.
5. Run clickhouse_server_info to check the connection.

Workflow

• Explore: clickhouse_list_databases, then clickhouse_list_tables for one database, clickhouse_describe_table for the columns and keys, clickhouse_show_create_table for the engine, sorting key and partitioning; clickhouse_search_columns finds a column by name across databases.
• Ask questions: clickhouse_query with one statement. Filter on the sorting key and partition columns from clickhouse_show_create_table, aggregate in SQL (count(), sum(), uniq(), quantile(0.95)(x), toStartOfDay(ts)), and always end with LIMIT. Use EXPLAIN or EXPLAIN ESTIMATE before a query that may scan a large table.
• Operations: clickhouse_server_info, clickhouse_table_sizes, clickhouse_running_queries, clickhouse_recent_queries (failed queries have an exception_code).

Reading the answers: the JSON format returns meta (column names and types), data (rows), rows (row count) and statistics (elapsed seconds, rows and bytes read). 64-bit integers (UInt64, Int64) arrive as strings, so "12345678901" is a number. DateTime values are YYYY-MM-DD hh:mm:ss in the server time zone from clickhouse_server_info unless the column type names another. Sizes from formatReadableSize are binary units (KiB, MiB, GiB).

Limits: there is no row cap besides your LIMIT and the connector's response size limit, so aggregate rather than fetch raw rows. A ClickHouse Cloud service that idles wakes on the first query, which can take up to a minute. clickhouse_running_queries shows one replica of a Cloud service.

Errors: the body carries Code: <n>. DB::Exception: .... Code 164 (READONLY) means the statement writes or changes a setting; 497 (ACCESS_DENIED, HTTP 403) a missing GRANT; 60 (UNKNOWN_TABLE) and 81 (UNKNOWN_DATABASE) a wrong name; 62 (SYNTAX_ERROR) bad SQL; 159 or 241 a timeout or memory limit (narrow the query). 401 or 516 (AUTHENTICATION_FAILED) means a wrong user or password.