---
title: "ClickHouse MCP Server: review, setup & limitations · Undominated.ai"
canonical: https://undominated.ai/mcp-servers/clickhouse/
description: "Queries ClickHouse and inspects table metadata, with read-only SQL by default and separate authentication for network transports."
---

# ClickHouse MCP Server: review, setup & limitations · Undominated.ai

> Queries ClickHouse and inspects table metadata, with read-only SQL by default and separate authentication for network transports.

[← Explore all mcp servers](/mcp-servers/)

ANALYTICS DATABASES / ClickHouse

# ClickHouse MCP Server

Queries ClickHouse and inspects table metadata, with read-only SQL by default and separate authentication for network transports.

 [See setup guidance ↓](#setup)[Original source ↗](https://github.com/ClickHouse/mcp-clickhouse)

SOURCE REVIEW

 Reviewed 2026-10-13
 Evidence 4 linked sources
 Publisher ClickHouse
 Licence [Apache-2.0 ↗](https://github.com/ClickHouse/mcp-clickhouse/blob/d21fe75a6f09afbfbe4cd5063372020bbe62c491/LICENSE)
 Revision d21fe75a6f09
 [Read what was—and wasn’t—checked ↓](#review)

“An MCP server for ClickHouse.”

 [ClickHouse · upstream description ↗](https://github.com/ClickHouse/mcp-clickhouse/blob/d21fe75a6f09afbfbe4cd5063372020bbe62c491/README.md) Our analysis follows below.

01 / THE REASONING

## Why this made the selection.

 - Documents query permissions and HTTP caller authentication separately.
- Supports metadata inspection and parameterized SQL, useful for targeted analytics investigations.

### A good fit for

 - Inspecting schemas and running analytical queries under a limited ClickHouse user.
- Querying local files or URLs in place with chDB’s in-process engine, after installing the optional chdb extra.

### Weigh up before choosing

 - Read-only queries can still consume substantial database resources.
- The server-side write guard is described as best effort; ClickHouse grants remain the permission boundary.

02 / THE REVIEW RECORD

## What we actually inspected.

Source review has boundaries. A clear record is more useful than a “safe” badge.

### Material inspected

 - README.md (tools, security, configuration, write access and destructive-operation sections)
- pyproject.toml
- mcp_clickhouse/mcp_server.py
- LICENSE

### Our findings

 - CLICKHOUSE_ALLOW_WRITE_ACCESS defaults false; writes require an explicit change.
- HTTP/SSE requires a configured bearer token or FastMCP auth provider unless authentication is deliberately disabled; the health probe is unauthenticated.
- mcp_server.py registers list_databases, list_tables and run_query while CLICKHOUSE_ENABLED is true (the default). It adds run_chdb_select_query and the chdb_initial_prompt prompt only when chDB is enabled and importable.
- DROP, TRUNCATE, DELETE, UPDATE and the other statements the README lists need CLICKHOUSE_ALLOW_DROP=true on top of CLICKHOUSE_ALLOW_WRITE_ACCESS=true. The README says this gate is not server-enforced; read-only mode is enforced with readonly=1.
- The README’s Claude Desktop block launches uv run --with mcp-clickhouse --python 3.12 mcp-clickhouse and passes host, port, user, password and role as placeholder environment values.
- Since the previous pin the README adds Agents Schema guidance: the server instructions suggest reading AGENTS.ROOT through run_query. The README says no metadata is fetched automatically.

### Not established by this review

 - Server startup, authentication and tool execution were not tested.

The review applies to the material and revision named here. A newer upstream release can change its behavior.

03 / PUT IT TO WORK

## Connect a server deliberately.

[Upstream setup instructions ↗](https://github.com/ClickHouse/mcp-clickhouse/blob/d21fe75a6f09afbfbe4cd5063372020bbe62c491/README.md)

DOCUMENTED COMMAND

 uv run --with mcp-clickhouse --python 3.12 mcp-clickhouse Copy command ↗

Copying does not execute this command. It may retrieve a newer version than the reviewed source.

 - Follow the documented client launch configuration and configure the ClickHouse connection.
- Keep write access disabled for exploration; configure caller authentication before using a network transport.
- The command above is the command and args of the README’s Claude Desktop block, not a separate installer. It was not run.

### Before you start

 - Python/uv or the documented container runtime and a ClickHouse user.

### Documented configuration example

Use the client and authentication context described in the setup guidance. Configuration formats vary between hosts.

 {
 "mcpServers": {
 "mcp-clickhouse": {
 "command": "uv",
 "args": [
 "run",
 "--with",
 "mcp-clickhouse",
 "--python",
 "3.12",
 "mcp-clickhouse"
 ],
 "env": {
 "CLICKHOUSE_HOST": "<clickhouse-host>",
 "CLICKHOUSE_PORT": "<clickhouse-port>",
 "CLICKHOUSE_USER": "<clickhouse-user>",
 "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
 "CLICKHOUSE_ROLE": "<clickhouse-role>",
 "CLICKHOUSE_SECURE": "true",
 "CLICKHOUSE_VERIFY": "true",
 "CLICKHOUSE_CONNECT_TIMEOUT": "30"
 }
 }
 }
} Copy configuration ↗

### Compatibility

An MCP client supporting stdio, SSE, Streamable HTTP. · Python/uv or the documented container runtime and a ClickHouse user.

### Implementation

Python

### Transports

stdio · SSE · Streamable HTTP

### Analytics databases / Configured credentials or local access

 - Reads ClickHouse schemas and query results; explicit write mode can alter data or schema.
- Optional chDB functionality can access local data separately from the remote database.
- Connects as the ClickHouse user and password set in its environment. HTTP and SSE callers must present a bearer token or pass a FastMCP auth provider unless authentication is disabled.

### Cost model

ClickHouse hosting and query compute determine cost.

04 / FOLLOW THE EVIDENCE

## The source trail.

Our notes are separate from the original resource. Check upstream before adopting a new version.

 - [Official documentation ↗](https://github.com/ClickHouse/mcp-clickhouse/blob/d21fe75a6f09afbfbe4cd5063372020bbe62c491/README.md) Checked 2026-10-13 https://github.com/ClickHouse/mcp-clickhouse/blob/d21fe75a6f09afbfbe4cd5063372020bbe62c491/README.md Supports: summary, whySelected, bestFor, limitations, install, access, compatibility, transports, configExample, review
- [Applicable source licence ↗](https://github.com/ClickHouse/mcp-clickhouse/blob/d21fe75a6f09afbfbe4cd5063372020bbe62c491/LICENSE) Checked 2026-10-13 https://github.com/ClickHouse/mcp-clickhouse/blob/d21fe75a6f09afbfbe4cd5063372020bbe62c491/LICENSE Supports: license
- [Implementation: pyproject.toml ↗](https://github.com/ClickHouse/mcp-clickhouse/blob/d21fe75a6f09afbfbe4cd5063372020bbe62c491/pyproject.toml) Checked 2026-10-13 https://github.com/ClickHouse/mcp-clickhouse/blob/d21fe75a6f09afbfbe4cd5063372020bbe62c491/pyproject.toml Supports: language, review
- [Implementation: mcp_clickhouse/mcp_server.py ↗](https://github.com/ClickHouse/mcp-clickhouse/blob/d21fe75a6f09afbfbe4cd5063372020bbe62c491/mcp_clickhouse/mcp_server.py) Checked 2026-10-13 https://github.com/ClickHouse/mcp-clickhouse/blob/d21fe75a6f09afbfbe4cd5063372020bbe62c491/mcp_clickhouse/mcp_server.py Supports: language, review, Tool list

KEEP COMPARING

## Other approaches to consider.

Related by category or shared topics. These are alternatives to inspect, not a measured quality order.

 [### CrateDB MCP Server ↗ Python MCP server from the crate organisation that runs SQL against a CrateDB cluster over its HTTP endpoint behind a SELECT-only check, reads table columns, table metadata and cluster health, lists a curated CrateDB documentation index, and fetches documentation pages by link under three permitted URL prefixes.](/mcp-servers/cratedb/)[### Teradata MCP Server ↗ Explore Teradata tables, profile data and investigate workloads using selectable tool modules.](/mcp-servers/teradata/)[### Firebolt MCP Server ↗ Go MCP server from Firebolt that connects a client to Firebolt Cloud or Firebolt Core, runs SQL, and exposes Firebolt documentation tools.](/mcp-servers/firebolt/)

 [AI Tools ↗](/tools/)[Skills ↗](/skills/)[Agents ↗](/agents/)[MCP Servers ↗](/mcp-servers/)[Workflows ↗](/workflows/)

## Continue your investigation

 - [Inspect resource evidence](/tools/)
- [Choose a host](/agents/)
- [Inspect reusable workflows](/skills/)
- [Use Undominated data](/api/)
