MCP Clickhouse logo

MCP Clickhouse

by ClickHouse

Query ClickHouse, inspect schemas, bind SQL parameters, and optionally run queries through embedded chDB.

Install MCP Clickhouse

Pick your client, then add it in one click or paste the config.

STDIOPython
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "clickhouse-mcp-clickhouse": {
      "command": "uvx",
      "args": [
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_ALLOW_WRITE_ACCESS": "YOUR_VALUE_HERE",
        "CLICKHOUSE_ALLOW_DROP": "YOUR_VALUE_HERE"
      }
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

Values are written into the snippet above so you can paste it as is. They never leave your browser.

Automated check passed— started and listed 3 tools correctly ().

Overview

ClickHouse/mcp-clickhouse exposes ClickHouse database discovery, table metadata, and SQL execution through MCP. Queries are read-only by default, support named ClickHouse parameters, and can use DESCRIBE or EXPLAIN ESTIMATE for preflight checks. An optional chDB tool runs SQL through an embedded ClickHouse engine against data sources such as files, URLs, and databases. Reach for it when an agent needs governed analytical access to ClickHouse or lightweight embedded ClickHouse queries.

Use cases

  • Inspect ClickHouse databases and table schemas before generating SQL
  • Run read-only analytical queries with typed named parameters
  • Check query output columns before execution
  • Estimate MergeTree reads before an expensive SELECT
  • Query local or remote sources through embedded chDB

Key features

  • ClickHouse database and table discovery
  • Paginated table metadata with filters
  • Read-only SQL execution by default
  • Typed named query parameters
  • DESCRIBE and EXPLAIN ESTIMATE checks
  • Optional embedded chDB query tool

Tools3

What MCP Clickhouse lets your agent do. Expand a tool for its parameters.

Verified live~787 tokens of context

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked

Recent health check succeeded.

29/29 checks healthy over the last 96d

What it can do

From the 3 tools this server returned when we ran it.

Runs commands · 1Can delete or modify data · 1Handles credentials · 1Read-only tools · 2
Network at startup2 connections
Files written at startup12

Observed 2026-11-12 in an isolated sandbox. A description of reach, not a security audit.

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 10d ago via OSV.dev · mcp-clickhouse (PyPI)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars905Stargazers on the source repository.
Last commit1d agoMost recent push to the default branch.
Availability100%Our rolling endpoint + install checks that succeeded.
Install checkPassedOur sandbox started it and listed its tools.
Tools exposed3Callable tools this server registers over MCP.
Directory activity8 viewsConfig copies, upvotes, and views on AllMCPs.

How MCP Clickhouse works

What ClickHouse/mcp-clickhouse does

ClickHouse/mcp-clickhouse gives MCP clients access to ClickHouse cluster metadata and SQL operations. Agents can enumerate databases, inspect tables, and execute queries while receiving JSON-encoded results. Table discovery can include schema details, comments, row and column counts, the table creation query, and pagination metadata.

The package also provides an optional chDB capability. After installing the chdb extra, agents can execute SQL with chDB's embedded ClickHouse engine and query data from sources such as files, URLs, and databases without an ETL step.

How it works

list_databases returns the databases visible on the configured ClickHouse cluster. list_tables takes a database name and supports table-name filters, page sizes, single-use continuation tokens, and an option to omit detailed column metadata for smaller responses. Pagination tokens remain valid for up to one hour.

run_query executes SQL against ClickHouse. It accepts named values through ClickHouse placeholders such as {id:UInt32} and {name:String}. Values are supplied separately in a params object and may be JSON scalars, nulls, or arrays when compatible with the declared ClickHouse type. Large integers outside JavaScript's safe range are represented as decimal strings in results and metadata, and should also be passed as decimal strings when exactness matters.

The same query tool can run DESCRIBE (<query>) to inspect output columns and types, or EXPLAIN ESTIMATE <query> to estimate parts, rows, and marks read from MergeTree-family tables. These checks do not execute the query body, although analysis can execute scalar subqueries. Estimates describe expected reads rather than runtime or result size.

Setup and configuration

Connect the server to a ClickHouse cluster using the runtime's ClickHouse connection configuration. Queries begin in read-only mode. Set CLICKHOUSE_ALLOW_WRITE_ACCESS=true to permit DDL and DML, and set CLICKHOUSE_ALLOW_DROP=true as an additional gate for destructive operations such as DROP, TRUNCATE, DELETE, and UPDATE. The destructive-operation setting is an accident guard, not a security boundary.

For embedded queries, install the optional package extra with pip install 'mcp-clickhouse[chdb]'. HTTP and SSE deployments expose /health; it returns 200 OK when the ClickHouse connection probe succeeds and 503 when the connection fails or the probe exceeds two seconds.

Tools and capabilities

  • list_databases: enumerate available ClickHouse databases.
  • list_tables: inspect tables, metadata, filters, and paginated results.
  • run_query: execute SQL with optional named parameter binding.
  • run_query preflight checks: use DESCRIBE for result schemas and EXPLAIN ESTIMATE for estimated MergeTree reads.
  • run_chdb_select_query: execute SQL through the optional embedded chDB engine.

Python %s and %(name)s formatting, as well as the driver's $name$ raw binary parameters, are not supported. JSON objects and lists cannot bind directly to ClickHouse Tuple and Map types. Parameter values are excluded from the server's normal SQL log messages but can appear in errors and backend logs.

Results preserve safe-range integers as JSON numbers. Larger integers are returned as decimal strings so JavaScript clients do not lose precision. The server supports modern sessionless MCP requests and legacy initialization handshakes across the protocol versions described by the project.

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about MCP Clickhouse

ClickHouse/mcp-clickhouse is an MCP server that connects AI clients to ClickHouse clusters for database discovery, table metadata inspection, and SQL execution. It provides `list_databases`, `list_tables`, and `run_query`, with optional named parameters, schema checks, read estimates, and an embedded chDB query tool.

Set `CLICKHOUSE_ALLOW_WRITE_ACCESS=true` to allow DDL and DML through `run_query`. Destructive statements also require `CLICKHOUSE_ALLOW_DROP=true`. Queries are read-only by default, and the destructive-operation setting is only an accident guard rather than a security boundary.

Use ClickHouse named placeholders such as `{id:UInt32}` in the SQL and provide matching values in the `params` object. Values can be JSON scalars, nulls, or compatible arrays. Pass large exact integers as decimal strings; Python percent formatting and `$name$` parameters are unsupported.

Use `DESCRIBE (<query>)` to inspect result columns and types, or `EXPLAIN ESTIMATE <query>` to estimate parts, rows, and marks read from MergeTree-family tables. Both checks are read-only and avoid running the query body, but analysis can execute scalar subqueries.

Related MCP servers

Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewMCP Clickhouse AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/clickhouse-mcp-clickhouse?style=directory)](https://allmcps.com/mcp/clickhouse-mcp-clickhouse)
HTML Embed
<a href="https://allmcps.com/mcp/clickhouse-mcp-clickhouse"><img src="https://allmcps.com/api/badge/clickhouse-mcp-clickhouse?style=directory" alt="MCP Clickhouse on AllMCPs" /></a>