# ClickHouse — MCP Server

> Run analytical SQL over billions of rows in natural language.

**Source:** https://mcpplaygroundonline.com/mcp-servers/clickhouse  
**Transport:** stdio  
**Requires auth:** Yes

---

## What it does

The server keeps its surface deliberately small: three tools for the cluster and one for chDB. list_databases and list_tables give the model the schema context it needs — including column types, row counts and the table engine, which matters a lot when writing efficient ClickHouse SQL — and run_select_query executes the query. Queries run with readonly enabled by default, so an agent cannot mutate or drop anything even if it decides to try; that default is the single most important thing about deploying this server. The fourth tool, run_chdb_select_query, runs SQL through chDB’s embedded engine, which can read Parquet, CSV and JSON straight off a URL or local path. That turns ad-hoc file analysis into a query rather than an ETL job. Connection is by environment variables and works identically against ClickHouse Cloud and a self-managed cluster.

## Tools exposed

- list_databases — enumerate the databases on the cluster
- list_tables — schemas, column types, row counts and table engines for a database
- run_select_query — execute analytical SQL, read-only by default
- run_chdb_select_query — query Parquet, CSV, JSON or a remote URL through chDB

## Example queries you can run

- "What are the top 20 event types by volume in the last 7 days, and how is that trending?"
- "Find the slowest queries in system.query_log and what they have in common."
- "Break down signups by country and referrer for last month."
- "Query this Parquet file on S3 and tell me the distribution of the amount column."

## Details

- **Recommended model:** anthropic/claude-sonnet-4.5 — ClickHouse SQL rewards knowing the engine and partition key. Sonnet 4.5 reads the schema first and writes queries that use them instead of scanning everything.
- **Transport:** stdio
- **Authentication:** Required — ClickHouse host, user and password by environment variable. Create a dedicated read-only user scoped to the databases the agent should see.
- **Official source:** [ClickHouse MCP integrations — official documentation](https://clickhouse.com/docs/use-cases/AI/MCP)

## Connecting to ClickHouse

### Environment variables

- `CLICKHOUSE_HOST` (required) — Hostname of the ClickHouse server, e.g. abc123.us-east-1.aws.clickhouse.cloud.
- `CLICKHOUSE_USER` (required) — Username. Use a dedicated read-only user rather than default.
- `CLICKHOUSE_PASSWORD` (required) — Password for that user.
- `CLICKHOUSE_PORT` — Defaults to 8443 when secure is true, 8123 otherwise.
- `CLICKHOUSE_SECURE` — HTTPS on or off. Defaults to true — leave it on for anything remote.
- `CLICKHOUSE_DATABASE` — Default database for queries that do not qualify a table name.

### Client configuration

**uv / uvx against ClickHouse Cloud**

The same configuration works against a self-managed cluster; only the host changes.

```
{
  "mcpServers": {
    "clickhouse": {
      "command": "uv",
      "args": ["run", "--with", "mcp-clickhouse", "--python", "3.13", "mcp-clickhouse"],
      "env": {
        "CLICKHOUSE_HOST": "abc123.us-east-1.aws.clickhouse.cloud",
        "CLICKHOUSE_USER": "readonly_agent",
        "CLICKHOUSE_PASSWORD": "YOUR_PASSWORD",
        "CLICKHOUSE_SECURE": "true"
      }
    }
  }
}
```

**The ClickHouse SQL playground (no account needed)**

A public read-only demo instance — the fastest way to see what the server does before pointing it at your own data.

```
{
  "mcpServers": {
    "clickhouse": {
      "command": "uv",
      "args": ["run", "--with", "mcp-clickhouse", "--python", "3.13", "mcp-clickhouse"],
      "env": {
        "CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
        "CLICKHOUSE_USER": "demo",
        "CLICKHOUSE_PASSWORD": "",
        "CLICKHOUSE_SECURE": "true"
      }
    }
  }
}
```

## Frequently asked questions

### What is the ClickHouse MCP server?

It is the official MCP server from ClickHouse, published as mcp-clickhouse. It exposes database and table discovery plus read-only analytical SQL to an AI agent, and bundles chDB for querying files and URLs directly.

### Can an agent modify or drop data through it?

Not with the defaults. Queries execute with the readonly setting enabled, so anything other than a SELECT is rejected by ClickHouse itself. Back that up with a dedicated read-only user and the boundary holds even if the configuration changes.

### What is chDB and why is it bundled?

chDB is ClickHouse as an embedded engine with no server. run_chdb_select_query uses it to run SQL directly over Parquet, CSV or JSON at a local path or remote URL, so an agent can analyse a file without anyone loading it into a table first.

### Does it work with ClickHouse Cloud?

Yes, and that is the common case. Point CLICKHOUSE_HOST at your Cloud hostname with CLICKHOUSE_SECURE set to true. The same server works against a self-managed cluster with no other changes.

### How do I stop a model running an expensive query?

Give the agent user a ClickHouse settings profile with max_execution_time, max_result_rows and max_memory_usage set. That is enforced server-side, which is a far stronger guarantee than asking the model to be careful in a prompt.

---

_Test this server across 40+ models on MCP Playground: https://mcpplaygroundonline.com/mcp-servers/clickhouse — free, no install._