How to Connect ClickHouse to Claude via MCP

💡 No install? Use cloud.anythingmcp.com directly. Sign in, click Connectors → ClickHouse, paste your credentials, mint an MCP API key and you're done. No Docker, no git clone, no local server.

ClickHouse + Claude

Let any AI agent query a ClickHouse server or ClickHouse Cloud service in read-only mode over the HTTP interface: list databases, tables and columns, read CREATE statements, check table sizes, see running and recent queries, and run any SELECT. Every request carries readonly=1, so ClickHouse itself refuses writes.

Prerequisites

See the full setup instructions baked into the connector (visible in the in-app store when you select the connector). The required environment variables for this connector are:

CLICKHOUSE_URL, CLICKHOUSE_USER, CLICKHOUSE_PASSWORD

Step 1 — Get credentials

Setting up takes about 3 minutes. You need the HTTPS address of a ClickHouse server or ClickHouse Cloud service and a user that may read.

1. Put the address of the HTTP interface, with its port, into CLICKHOUSE_URL. On 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. Scheme, host and port only, no path.
2. Create a dedicated user that may only read, for example CREATE USER mcp_reader IDENTIFIED BY '...'; GRANT SELECT ON analytics.* TO mcp_reader;. For clickhouse_table_sizes, clickhouse_running_queries and clickhouse_recent_queries also grant GRANT SELECT ON system.parts, system.processes, system.query_log TO mcp_reader. On ClickHouse Cloud the built-in user is default.
3. Do not give that user a settings profile with readonly = 2: the connector sets readonly=1 on each request and ClickHouse rejects that change under readonly = 2. readonly = 0 or 1 both work.
4. Put the user name into CLICKHOUSE_USER and its password into CLICKHOUSE_PASSWORD. They are sent as HTTP Basic auth.
5. ClickHouse Cloud only: the service's IP access list must allow the address AnythingMCP calls from.
6. Install the connector and run clickhouse_server_info: it shows version, uptime, server time zone, the signed-in user, its default database and its effective readonly level.

What it reads: the databases the user can see with engine and comment, the tables and views of one database (engine, total rows and bytes, readable size, comment), the columns of a table with type, default expression and whether they belong to the partition, sorting or primary key, the CREATE statement of a table or view (engine, ORDER BY, PARTITION BY, TTL, settings, or the SELECT behind a view), and columns found by name across databases with clickhouse_search_columns. For operations: storage per table from the active parts, the queries running now and the finished or failed queries from the query log. clickhouse_query runs one statement of type SELECT, WITH, SHOW, DESCRIBE, EXPLAIN or EXISTS.

What it writes: nothing. Every request carries the setting readonly=1, so ClickHouse refuses INSERT, ALTER, CREATE, DROP and SET whatever the user's grants. Because there are no write tools, no tool is switched off at install.

How the AI queries: it explores with clickhouse_list_databases, clickhouse_list_tables, clickhouse_describe_table and clickhouse_show_create_table, then filters on the sorting key and partition columns, aggregates in SQL (count(), sum(), uniq(), quantile(0.95)(x), toStartOfDay(ts)) and always ends with LIMIT. Before a query that may scan a large table it can run EXPLAIN or EXPLAIN ESTIMATE. A query is one statement without a FORMAT clause and without a trailing semicolon; database sets the default database for unqualified table names.

Data formats: the JSON format returns meta (column names and types), data (rows), rows (row count) and statistics (elapsed seconds, rows and bytes read). clickhouse_query can also answer in JSONCompact (rows as arrays, smaller), CSVWithNames or TabSeparatedWithNames. 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).

Paging and limits: there is no paging and no row cap besides your LIMIT and the connector's response size limit; the whole result comes back in one answer, so aggregate rather than fetch raw rows. clickhouse_search_columns returns up to 500 matches. clickhouse_recent_queries returns the last 100 queries within minutes (default 60). clickhouse_running_queries shows only the node that answers, on ClickHouse Cloud one replica of the service. A Cloud service that idles wakes on the first query, which can take up to a minute.

Common errors: the body carries Code: <n>. DB::Exception: .... Code 164 (READONLY) means the statement writes or changes a setting. 497 (ACCESS_DENIED, HTTP 403) means a missing GRANT, or on ClickHouse Cloud an IP access list that does not allow this server. 60 (UNKNOWN_TABLE) and 81 (UNKNOWN_DATABASE) mean 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. Nothing answering at the address usually means a wrong port or a path in CLICKHOUSE_URL.

The connector does not insert, update or delete data, does not create or change tables, and does not manage ClickHouse Cloud services (start, stop, scaling, backups, costs): for that install the separate ClickHouse Cloud connector.

Step 2 — Install the adapter

curl -fsSL https://raw.githubusercontent.com/HelpCode-ai/anythingmcp/main/docker-compose.quickstart.yml -o docker-compose.yml
printf 'JWT_SECRET=%s\nENCRYPTION_KEY=%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env
docker compose up -d

Step 3 — Add the connector in Claude

Your server URL: in AnythingMCP, open MCP Servers → the server this connector is on, and copy its URL (https://cloud.anythingmcp.com/mcp/…). Use it wherever this guide shows YOUR_SERVER_ID.

Recommended path: works on claude.ai web without editing any config file.

1. In Claude, open Customize → Connectors.
2. Click +, then Add custom connector.
3. Enter a name, e.g. ClickHouse, and the remote MCP server URL https://cloud.anythingmcp.com/mcp/YOUR_SERVER_ID, then click Add.
4. Click Connect and sign in to AnythingMCP (OAuth) to allow access.

All tools below appear in your chat: start typing prompts.

Available tools

Example prompts

• "Which databases and tables are there, and which tables take the most disk space?"
• "How many events per day did we have in analytics.events over the last 30 days?"
• "Where is a column like customer_id stored? Search across all databases."
• "Show me the queries that failed in the last hour with their error code."
• "What are the top 10 countries by revenue this month? Check the sorting key first so the query stays cheap."

FAQ

Does it work with Claude Code as well as Claude Desktop? Yes, point both at https://cloud.anythingmcp.com/mcp/YOUR_SERVER_ID.

Next steps

• Connector landing page
• Connect to ChatGPT
• Connect to Cursor
• Connect to Gemini
• Connect to Meta Muse
• Connect to Microsoft Copilot