How to use Claude with ClickHouse
Connect Claude or ChatGPT to ClickHouse. How to set it up and get your team querying event data in natural language.
ClickHouse is the go-to warehouse for teams that need fast analytics on large volumes of event data. If you're tracking product events, logs, or time-series data at scale, ClickHouse is probably already on your shortlist. Here's how to connect it to Claude so your team can query it in natural language.
Why ClickHouse is different
ClickHouse is a column-oriented database built for real-time analytics. It handles billions of rows without breaking a sweat. But it also has quirks that trip up LLMs:
- ClickHouse SQL dialect: It's similar to standard SQL but has its own functions, aggregation syntax, and array handling. Claude needs to know to use
toStartOfMonth()instead ofDATE_TRUNC. - Materialized views and engines: ClickHouse tables use different engines (MergeTree, AggregatingMergeTree, etc.) that affect how you query them.
- Event-heavy schemas: ClickHouse databases tend to have wide, denormalized event tables with hundreds of columns. Without context, Claude doesn't know which columns matter.
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's 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 ClickHouse's SQL dialect. But for the rest of your team, the same problems apply as with any direct connection:
- 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 + Contextflo
Contextflo connects to ClickHouse Cloud or self-hosted ClickHouse instances. It scans your schema and generates context that includes ClickHouse-specific details:
- Table and column descriptions auto-generated from your schema
- ClickHouse-aware SQL generation with correct functions and syntax
- Metric definitions that handle ClickHouse aggregation patterns
- Context for wide event tables that highlights the columns that matter
Your team asks questions in Claude. Contextflo provides the context, Claude writes ClickHouse-compatible SQL, and the query runs against your instance. Results come back in seconds.
Setting it up
- Create a read-only user in ClickHouse with SELECT privileges on the databases you want to expose.
- Add the connection in Contextflo with host, port, database, and credentials.
- Select tables: choose which tables to include. For wide event tables, you can annotate which columns are most useful.
- Review context: Contextflo generates descriptions automatically. Refine the important ones.
- Connect Claude: install the Contextflo MCP server and start querying.
Common ClickHouse + Claude use cases
“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 the checkout_started event but not checkout_completed in the last 30 days?”
These queries are fast in ClickHouse, often under a second even on billions of rows. With proper context, Claude writes them correctly on the first try.
Get started
Connect your ClickHouse instance to Contextflo and start asking questions in Claude. Works with ClickHouse Cloud and self-hosted deployments.