ClickHouse MCP Server

Official

Official ClickHouse server: read-only SQL queries plus database/table exploration and chDB support.

Verified

stdio (local)

API key

Python

View repo 1.0k Website

Add to your client

Copy the config for your MCP client and paste it into its config file.

Install / run

uvx mcp-clickhouse

Paste into ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "clickhouse-mcp-server": {
      "command": "uvx",
      "args": [
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_PORT": "8443",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>"
      }
    }
  }
}

Requires `uv` (the Python package runner). Install it from https://docs.astral.sh/uv/ if `uvx` is not found.

Before you start

Python 3.10+ and the uv package manager (or pip)
A ClickHouse instance and credentials: CLICKHOUSE_HOST, CLICKHOUSE_USER, CLICKHOUSE_PASSWORD (ClickHouse Cloud, a local server, or the ClickHouse SQL Playground all work)
Optionally chDB if you want to query files directly — install the extra with pip install 'mcp-clickhouse[chdb]' and set CHDB_ENABLED=true
For remote/HTTP deployments: optionally a bearer token (CLICKHOUSE_MCP_AUTH_TOKEN) or an OAuth/OIDC provider

About ClickHouse MCP Server

ClickHouse MCP Server is the official Model Context Protocol server from ClickHouse. It connects a ClickHouse deployment (ClickHouse Cloud or self-hosted) to AI assistants, letting them explore databases and tables and run SQL queries through MCP tools.

Queries run in read-only mode by default, so an agent can analyze data without risk of mutating it; write access and destructive operations are off unless you explicitly opt in with environment flags. The server also bundles chDB, ClickHouse's embedded SQL engine, so you can query data files (Parquet, CSV, S3, etc.) directly through the same interface without a running ClickHouse server.

It's a Python package (mcp-clickhouse) usually launched with uv. It supports stdio, HTTP, and SSE transports, connects via standard CLICKHOUSE_* environment variables, and offers a /health endpoint and optional bearer-token / OAuth auth for remote deployments.

Tools & capabilities (4)

run_query

Execute a SQL query against ClickHouse (read-only by default)

list_databases

List all databases in the ClickHouse instance

list_tables

List tables in a database, with pagination and filtering, including schema details

run_chdb_select_query

Run a SELECT query using the embedded chDB engine (e.g. over files/S3) without a ClickHouse server

When to use it

Use it when you want an AI assistant to answer analytical questions by writing and running SQL against ClickHouse
Use it when exploring an unfamiliar ClickHouse instance — discovering databases, tables, and column schemas
Use it when you need a safe, read-only connection so an agent can query production analytics data without risk of writes
Use it when you want to query Parquet/CSV/S3 data files directly via chDB without standing up a ClickHouse server
Use it when connecting Claude or another MCP client to the public ClickHouse SQL Playground for demos and learning

Quick setup

1Install via uv/pip; for file querying add the chdb extra: pip install 'mcp-clickhouse[chdb]'
2Add the server to your MCP client config (e.g. command: uv, args: run --with mcp-clickhouse --python 3.10 mcp-clickhouse)
3Set CLICKHOUSE_HOST / CLICKHOUSE_USER / CLICKHOUSE_PASSWORD (and CLICKHOUSE_PORT/SECURE as needed) in the env block
4Optionally set CHDB_ENABLED=true, and CLICKHOUSE_ALLOW_WRITE_ACCESS=true only if you need writes
5Restart your MCP client and verify with list_databases, then run a small run_query

Security notes

Queries run read-only by default, which is the recommended posture; only relax this for trusted workloads. Credentials are passed via env vars, so keep them out of shell history and use a least-privilege ClickHouse user.

ClickHouse MCP Server FAQ

Is it read-only or can it modify data?

Read-only by default (CLICKHOUSE_ALLOW_WRITE_ACCESS=false). You can enable writes explicitly, and destructive operations like DROP require an additional flag (CLICKHOUSE_ALLOW_DROP).

What is the chDB tool for?

run_chdb_select_query uses chDB, ClickHouse's embedded engine, to run SELECT queries directly over files and external sources (Parquet, CSV, S3, URLs) without needing a running ClickHouse server. Enable it with the chdb extra and CHDB_ENABLED=true.

Can I try it without my own ClickHouse server?

Yes. Point the CLICKHOUSE_* variables at the public ClickHouse SQL Playground (host sql-clickhouse.clickhouse.com, user demo, no password) to explore sample datasets, or use chDB over files.

Which transports does it support?

stdio by default, plus HTTP and SSE for remote deployments. Remote modes can be secured with a static bearer token or OAuth/OIDC, and a /health endpoint is provided for orchestration.

#clickhouse #olap #analytics #official

Alternatives to ClickHouse MCP Server

MCP Toolbox for Databases (BigQuery)

Databases

16k

Google's official MCP server with prebuilt BigQuery tools, querying datasets via Application Default Credentials.

Verified

stdio (local)

OAuth

10 tools

Updated 11 days agoRepo

Postgres MCP Pro

Databases

2.9k

Read/write Postgres access plus index tuning, EXPLAIN plans, and database health analysis for AI agents.

Verified

stdio (local)

API key

Python

9 tools

Updated 3 months agoRepo

Supabase MCP Server

Databases

2.7k

Official Supabase server: manage tables, run SQL, branches, configs and edge functions from your AI client.

Verified

HTTP (remote)

OAuth

TypeScript

12 tools

Updated 1 month agoRepo

Compare ClickHouse MCP Server with:

vs MCP Toolbox for Databases (BigQuery)vs Postgres MCP Pro vs Supabase MCP Server vs Neon MCP Server