How to Connect ClickHouse to Gemini 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 + Gemini

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 Gemini

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.

Gemini CLI reads MCP servers from ~/.gemini/settings.json (on Windows %USERPROFILE%\.gemini\settings.json). Add:

{
  "mcpServers": {
    "anythingmcp": {
      "httpUrl": "https://cloud.anythingmcp.com/mcp/YOUR_SERVER_ID",
      "headers": { "X-API-Key": "YOUR_MCP_API_KEY" }
    }
  }
}

1. Create an MCP API key in AnythingMCP under MCP Servers → your server → API keys, and paste it in place of YOUR_MCP_API_KEY.
2. Save the file and restart gemini.
3. Run /mcp inside Gemini CLI (or gemini mcp list in your shell): anythingmcp should show as connected.
4. Start prompting: Gemini CLI can now call the ClickHouse tools.

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

Where does Gemini CLI look for MCP servers? In ~/.gemini/settings.json for your user, or in .gemini/settings.json inside a project. gemini mcp list shows each server and whether it connects.

Next steps

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