# ClickHouse MCP (stackblaze fork)

Fork of [ClickHouse/mcp-clickhouse](https://github.com/ClickHouse/mcp-clickhouse) for
the kubero chat **feature MCP** broker. See [FORK.md](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`).

## 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)

```bash
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)

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

## Container

```bash
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](https://github.com/ClickHouse/mcp-clickhouse/blob/main/README.md).