Skip to main content
Glama
clickhouse-mcp

clickhouse-mcp

by stackblaze

ClickHouse MCP (stackblaze fork)

Fork of ClickHouse/mcp-clickhouse for the kubero chat feature MCP broker. See FORK.md for divergence notes.

One long-lived Deployment per workload cluster serves every ClickHouseInstallation add-on — the connection target arrives per request via HTTP headers, not at boot.

Tools (namespaced ch__* in chat)

Tool

Mode

Description

list_databases

read

List all databases

list_tables

read

List tables in a database (paginated)

run_query

read/write

Execute SQL (SELECT/SHOW in restricted; DDL/DML when unrestricted)

chDB tools (run_chdb_select_query) are disabled in the kubero Deployment (CHDB_ENABLED=false).

Related MCP server: clickhouse-mcp-server

Kubero headers

X-Kubero-DB-URI: clickhouse://user:pass@clickhouse-<instance>.<ns>.svc.cluster.local:9000[/db]
X-Kubero-Access-Mode: restricted | unrestricted

Port 9000 in the URI is the CHI native port; the MCP connects over HTTP on 8123 on the same Service.

Run locally (stdio, single cluster)

export CLICKHOUSE_HOST=localhost
export CLICKHOUSE_USER=default
export CLICKHOUSE_PASSWORD=
export CLICKHOUSE_SECURE=false
export CLICKHOUSE_PORT=8123
uv run mcp-clickhouse

Run like kubero (HTTP, connection-from-request)

uv run mcp-clickhouse \
  --transport streamable-http \
  --connection-from-request \
  --streamable-http-host 0.0.0.0 \
  --streamable-http-port 3010

Container

docker build -t ghcr.io/stackblaze/clickhouse-mcp:local .
docker run --rm -p 3010:3010 ghcr.io/stackblaze/clickhouse-mcp:local \
  --transport streamable-http \
  --connection-from-request \
  --streamable-http-host 0.0.0.0 \
  --streamable-http-port 3010

Image: ghcr.io/stackblaze/clickhouse-mcp:<tag>

Upstream docs

For full upstream configuration (auth providers, chDB, middleware hooks), see the original README.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables interaction with ClickHouse databases via MCP, providing tools to list databases and tables and execute safe SELECT, SHOW, and DESCRIBE queries.
      78 npm
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to query and manage ClickHouse databases, supporting SELECT queries, DDL/DML statements, and metadata listing.
      5
      4 npm
      MIT