Provides read-only access to a ClickHouse instance, enabling schema exploration, data sampling, and execution of guarded SELECT/SHOW/DESCRIBE/EXPLAIN queries to investigate observability data like logs, metrics, and traces.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@clickhouse-mcp Why did p99 latency spike at 02:14?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A read-only Model Context Protocol server for ClickHouse. It gives an AI agent a small set of tools to explore a ClickHouse instance and investigate observability data (logs, metrics, traces) without being able to write or mutate anything.
Built as a reference for wiring agents onto a petabyte-scale analytics platform: the agent discovers the schema, samples data, and runs guarded read-only SQL to answer questions like "why did p99 latency spike at 02:14?".
Tool | What it does |
|
|
|
|
|
|
|
|
|
|
| Arbitrary read-only SQL (SELECT/WITH/SHOW/DESCRIBE/EXPLAIN) |
Related MCP server: db-connect-mcp
Verb guard: only SELECT / WITH / SHOW / DESCRIBE / EXPLAIN / EXISTS are allowed;
write/DDL verbs (INSERT, CREATE, DROP, ALTER, TRUNCATE, …) are rejected.
Limits: every query sets max_result_rows and max_execution_time, and the rows
returned to the model are capped (with a truncation note) to protect its context window.
Defence in depth: still point this at a read-only ClickHouse user. The app-level guard is a first line, not the only one.
Node.js 20+
Any ClickHouse instance. Easiest is local docker (no setup, includes system.*
observability tables to play with):
docker run -d --name ch -p 8123:8123 -p 9000:9000 clickhouse/clickhouse-servergit clone <your-fork-url> clickhouse-mcp && cd clickhouse-mcp
npm install
cp .env.example .env # then edit if your ClickHouse needs authnpm run self-test
# Connecting to http://localhost:8123
# databases: [ 'default', 'system', 'INFORMATION_SCHEMA', ... ]
# version: [ { v: '25.x.x.x' } ]
# OKnpm startClaude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"clickhouse": {
"command": "npx",
"args": ["tsx", "/absolute/path/to/clickhouse-mcp/src/index.ts"],
"env": {
"CLICKHOUSE_URL": "http://localhost:8123",
"CLICKHOUSE_USERNAME": "default",
"CLICKHOUSE_PASSWORD": ""
}
}
}
}Claude Code:
claude mcp add clickhouse -e CLICKHOUSE_URL=http://localhost:8123 -- npx tsx /absolute/path/to/clickhouse-mcp/src/index.tsMCP Inspector (great for debugging the tools directly):
npx @modelcontextprotocol/inspector npx tsx src/index.tsThen ask an agent: "What tables are in the system database? Show recent slow queries from system.query_log grouped by minute."
MIT
Describe the columns and types of a table.
Inputs: table (required), database (required).
List all databases in ClickHouse.
Inputs: no named parameters.
List tables in a database.
Inputs: database (required).
Run a read-only SQL query against ClickHouse (SELECT/WITH/SHOW/DESCRIBE/EXPLAIN only). Results are capped to keep the agent's context small. Use it to investigate telemetry: group by time, aggregate, find anomalies, join logs/metrics/traces. Add LIMIT on big tables.
Inputs: sql (required).
Read a small sample of rows from a table to understand its shape. Defaults to 10 rows.
Inputs: table (required), database (required), limit.
Return the CREATE TABLE statement for a table (schema, engine, settings).
Inputs: table (required), database (required).
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 6 tools
Each tool targets a distinct operation: listing databases, listing tables, sampling rows, describing columns, showing the CREATE statement, and running arbitrary queries. While describe_table and show_create_table both expose schema information, their purposes are clearly separated by level of detail and use case. No two tools are likely to be confused.
The tool names mostly follow a consistent verb_noun pattern (list_databases, list_tables, describe_table, show_create_table, sample_rows). The exception is 'query', which is a single verb, but it is a reasonable outlier given its generic nature. Overall, the naming is predictable and easy to navigate.
Six tools is an ideal size for a ClickHouse exploration server, covering all essential read-only operations without unnecessary bloat. Each tool has a clear purpose and none feel redundant. The count is well-scoped for the server's stated goal of investigating telemetry data.
The tool set provides full coverage for the core workflows: discovering databases and tables, understanding table schemas via describe and CREATE statements, sampling data, and running arbitrary queries for deeper analysis. There are no obvious gaps for a read-only data exploration server; any additional needs can be fulfilled through the query tool.
Governed access to production AI-agent traces in an existing ClickHouse store.
Query your warehouse or a CSV with Claude/ChatGPT over MCP, governed by table-level ACL + audit.
Text-to-SQL MCP server: read-only queries on PostgreSQL, MySQL and SQL Server with your real schema
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
