ClickHouse MCP Server
Officialby ClickHouse
Ask Claude to analyze a billion rows in your ClickHouse cluster and get an answer in under a second. That is the reality once you wire up the official ClickHouse MCP server. It turns any MCP-compatible AI assistant into a direct interface to your columnar database -- no intermediary scripts, no copy-pasting SQL output into chat windows, no context lost between questions. The server exposes three core tools to the AI: run_query for executing SQL, list_databases for discovering what clusters contain, and list_tables for browsing schemas with pagination and optional column metadata. By default, every query runs in read-only mode, so there is zero risk of an AI accidentally mutating production data. If you explicitly need write access for ETL or data pipeline work, you opt in with environment flags -- and destructive operations like DROP require a second flag on top of that. The safety model is well thought out. What surprised me most during setup is the chDB integration. With a single environment variable (CHDB_ENABLED=true), you unlock an embedded ClickHouse engine that can query Parquet files, CSVs, and remote URLs directly -- no data loading step required. Point Claude at a 500MB Parquet file on S3 and ask questions about it. That alone is worth the install. Setup takes about five minutes. Install via pip or uv, drop the config block into your Claude Desktop settings (or any MCP client config), add your ClickHouse credentials as environment variables, and restart. The server supports stdio, HTTP, and SSE transports, with bearer token authentication baked in for production HTTP deployments. There is even a /health endpoint for monitoring. This pairs naturally with other MCP servers in a data engineering stack. Combine it with the GitHub MCP server for code-aware analytics workflows, or the Brave Search server to let Claude cross-reference your internal metrics against public benchmarks. ClickHouse is already powering analytics at Cloudflare, Uber, and eBay -- now your AI assistant speaks the same language those systems do.
Installation
Key Features
- ✓Execute read-only SQL queries against ClickHouse clusters with automatic safety enforcement -- write access requires explicit opt-in flags
- ✓List all databases and browse tables with pagination, filtering, and optional column detail inspection for schema discovery
- ✓Embedded chDB engine support lets you query Parquet files, CSVs, and remote URLs directly without any ETL or data loading
- ✓Three transport modes (stdio, HTTP, SSE) with bearer token authentication for production HTTP/SSE deployments
- ✓Destructive operation protection through a dual-flag system -- both ALLOW_WRITE_ACCESS and ALLOW_DROP must be true for DROP statements
- ✓Health monitoring endpoint (/health) returns server version and ClickHouse connection status for uptime checks
- ✓Configurable query timeouts and connection parameters via environment variables for fine-tuned cluster access
- ✓Middleware extension system via MCP_MIDDLEWARE_MODULE for custom request processing hooks and audit logging
Use Cases
- →Ask Claude to explore a new ClickHouse dataset by listing databases, browsing table schemas, and running exploratory queries -- all through natural conversation instead of switching between a SQL client and chat
- →Run ad-hoc analytics on production metrics by describing what you want in plain English and letting Claude generate and execute the ClickHouse SQL, then interpret results with context
- →Analyze large Parquet or CSV files on S3 using the embedded chDB engine without loading data into a database first -- just point Claude at the file URL and ask questions
- →Debug data pipeline issues by having Claude inspect table schemas, check row counts across partitions, and compare expected vs actual data distributions in your ClickHouse cluster
- →Generate weekly business reports by asking Claude to query your analytics tables, compute KPIs, and summarize trends -- turning a 30-minute SQL session into a 2-minute conversation
- →Onboard new team members to your data infrastructure by letting them ask Claude questions about what tables exist, what columns mean, and what the data looks like -- a self-service data catalog