Connect Claude to ClickHouse

ClickHouse is the go-to warehouse for teams that need fast analytics on large volumes of event data. If you are tracking product events, logs or time-series at scale it is probably already on your shortlist. Here is how to connect it to Claude so your team can query it in natural language.

Why ClickHouse is different

ClickHouse is column-oriented and built for real-time analytics. It handles billions of rows without breaking a sweat. It also has quirks that trip up LLMs:

• The SQL dialect. Similar to standard SQL but with its own functions, aggregation syntax and array handling. Claude needs to know to use toStartOfMonth() rather than DATE_TRUNC.
• Materialized views and table engines. ClickHouse tables use different engines (MergeTree, AggregatingMergeTree and others) that change how you should query them.
• Event-heavy schemas. ClickHouse databases tend toward wide, denormalised event tables with hundreds of columns. Without context, Claude has no idea which of them matter.

That third one is the real problem, and it is worse than it sounds. A model faced with a 200-column event table and no descriptions will pick a column that looks plausible by name. On a normalised schema a wrong guess usually errors. On a wide event table it returns a number, and the number looks fine.

Option 1: direct MCP connection

ClickHouse offers an official MCP server that lets Claude connect directly. ClickHouse Cloud also provides a remote MCP endpoint at mcp.clickhouse.cloud, so there is no local server to install. You authenticate, and Claude can list databases, inspect schemas and run SELECT queries.

This works for a data engineer who knows the schema and the dialect. For everyone else the usual gaps apply:

• No context about what tables and columns mean
• Claude may generate standard SQL instead of ClickHouse dialect
• No shared metric definitions
• No access control beyond database-level permissions

Option 2: ClickHouse plus Contextflo

Contextflo connects to ClickHouse Cloud or self-hosted instances. It reads your schema, source code and docs, and generates context that includes the ClickHouse-specific parts:

• Table and column descriptions generated from your schema, source code and docs
• ClickHouse-aware SQL generation with the correct functions and syntax
• Metric definitions that handle ClickHouse aggregation patterns
• Context for wide event tables that marks which columns actually matter

Your team asks questions in Claude, Contextflo supplies the context, Claude writes ClickHouse-compatible SQL, and the query runs against your instance.

Setting it up

1. Create a read-only user in ClickHouse with SELECT privileges on the databases you want to expose.
2. Add the connection in Contextflo with host, port, database and credentials.
3. Select tables. Choose which to include. For wide event tables, annotate which columns are most useful.
4. Review context. Descriptions are generated automatically. Refine the important ones.
5. Connect Claude. Install the Contextflo MCP server and start querying.

Step 3 deserves more time than it looks like it needs on a ClickHouse schema specifically. Narrowing a 200-column table down to the twenty columns people actually ask about is the single highest-value thing you can do here, and it improves accuracy more than any amount of prompt wording.

Common ClickHouse questions

What's the p95 latency for API requests over the last 24 hours, grouped by endpoint?

Show me the top 10 events by volume this week compared to last week.

What percentage of users triggered checkout_started but not checkout_completed in the last 30 days?

These are fast in ClickHouse, often under a second even across billions of rows. With the right context, Claude writes them correctly first time. Without it, the first two usually work and the third quietly does not, because a funnel question depends on knowing how your event table identifies a user and a session.

Here is a more in-depth look at Contextflo and how it works.