ClickHouse MCP Server: AI Queries on Columnar Data at Speed

What it is: The official MCP server from ClickHouse (ClickHouse/mcp-clickhouse, Python). It lets AI agents list databases and tables, inspect schemas, and run SELECT queries against ClickHouse Cloud, self-hosted clusters, or the free SQL playground — with every query forced to run read-only.

Why it matters for data work

ClickHouse aggregates billions of rows in sub-second time, which makes it the rare database where "just ask the agent to scan everything" is actually viable. Analytical questions that would need sampling elsewhere — funnel breakdowns, log analytics, event counts by dimension — come back fast enough for a conversational loop.

How do you install and configure it?

The server ships as the mcp-clickhouse Python package, run via uv. Connection details come from environment variables, not CLI flags:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": ["run", "--with", "mcp-clickhouse", "--python", "3.13", "mcp-clickhouse"],
      "env": {
        "CLICKHOUSE_HOST": "your-instance.clickhouse.cloud",
        "CLICKHOUSE_PORT": "8443",
        "CLICKHOUSE_USER": "default",
        "CLICKHOUSE_PASSWORD": "<password>",
        "CLICKHOUSE_SECURE": "true"
      }
    }
  }
}

That JSON works verbatim in Claude Desktop's claude_desktop_config.json and Cursor's .cursor/mcp.json. In Claude Code, the one-liner is:

claude mcp add clickhouse \
  -e CLICKHOUSE_HOST=your-instance.clickhouse.cloud \
  -e CLICKHOUSE_USER=default \
  -e CLICKHOUSE_PASSWORD=<password> \
  -e CLICKHOUSE_SECURE=true \
  -- uv run --with mcp-clickhouse --python 3.13 mcp-clickhouse

Is the ClickHouse MCP server read-only?

Yes — the server runs every statement with the ClickHouse setting readonly = 1, which rejects INSERT, ALTER, DROP, and any other write or DDL at the database level regardless of what SQL the model produces. As with any agent-facing credential, still prefer a dedicated user with narrow grants and a ClickHouse quota or max_execution_time limit: read-only protects your data, not your cluster's CPU.

Does it work with ClickHouse Cloud and self-hosted?

Both, plus two useful extras. For ClickHouse Cloud, use your instance hostname with port 8443 and CLICKHOUSE_SECURE=true. For self-hosted, point at your HTTP interface (commonly port 8123 with CLICKHOUSE_SECURE=false inside a private network). For a zero-setup demo, connect to the free sql-clickhouse.clickhouse.com playground as user demo. And for purely local work, the same server can expose chDB — ClickHouse's embedded engine — so an agent can query Parquet, CSV, or JSON files with ClickHouse SQL and no running server:

"env": {
  "CHDB_ENABLED": "true",
  "CHDB_DATA_PATH": "/path/to/chdb-data"
}

Example usage

Ask Claude "which endpoints had the highest p95 latency yesterday, hour by hour?" against a logs table. The agent lists tables, checks the schema, writes the quantile(0.95) aggregation with an hourly toStartOfHour group-by, and summarizes the outliers — a scan over hundreds of millions of rows that returns in seconds.

Troubleshooting

Common fixes, in order: (1) connection refused on Cloud — you used port 9440 (native) instead of 8443 (HTTPS); this server speaks HTTP. (2) auth failures — check CLICKHOUSE_USER; Cloud instances default to default, not your login email. (3) TLS errors self-hosting — set CLICKHOUSE_SECURE=false for plain HTTP on 8123. (4) uv not found — install it from astral.sh and use its absolute path in the config. (5) config edits ignored — fully restart Claude Desktop or Cursor; they read MCP config at launch only.

Author & links

Author: ClickHouse, Inc. (official)

Repo: github.com/ClickHouse/mcp-clickhouse

License: Apache-2.0

Related skills

New to the database itself? Start with our ClickHouse overview. For the same agent pattern on an OLTP database, see the Postgres MCP server; for local analytical files without any server, the DuckDB MCP server is the closest sibling to chDB mode.

← Back to MCP Servers