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)

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.