ClickHouse MCP Server

Name: ClickHouse MCP Server
Author: ClickHouse

Query and explore ClickHouse databases, or the embedded chDB engine, with SQL from an MCP client

Official · ClickHouse Python Local · stdio Databases Data and analytics

GitHub PyPI Website

82 popularity score ★ 903 ↓ 241k/mo

Connect your client

Local (PyPI)

Add in one click

Add to Cursor Add to VS Code Add to LM Studio

Opens the app, which asks before it adds the server. Then replace each <NAME> in its settings with your value.

Or add it by command or config

It needs CLICKHOUSE_HOST, CLICKHOUSE_USER, CLICKHOUSE_PASSWORD. Replace each <NAME> with your value.

Claude CodeTerminal

claude mcp add clickhouse -e CLICKHOUSE_HOST=<CLICKHOUSE_HOST> -e CLICKHOUSE_USER=<CLICKHOUSE_USER> -e CLICKHOUSE_PASSWORD=<CLICKHOUSE_PASSWORD> -- uv run --with mcp-clickhouse --python 3.12 mcp-clickhouse

Claude Desktopclaude_desktop_config.json

{
  "mcpServers": {
    "clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.12",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<CLICKHOUSE_HOST>",
        "CLICKHOUSE_USER": "<CLICKHOUSE_USER>",
        "CLICKHOUSE_PASSWORD": "<CLICKHOUSE_PASSWORD>"
      }
    }
  }
}

Cursor~/.cursor/mcp.json

{
  "mcpServers": {
    "clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.12",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<CLICKHOUSE_HOST>",
        "CLICKHOUSE_USER": "<CLICKHOUSE_USER>",
        "CLICKHOUSE_PASSWORD": "<CLICKHOUSE_PASSWORD>"
      }
    }
  }
}

VS Code.vscode/mcp.json

{
  "servers": {
    "clickhouse": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.12",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<CLICKHOUSE_HOST>",
        "CLICKHOUSE_USER": "<CLICKHOUSE_USER>",
        "CLICKHOUSE_PASSWORD": "<CLICKHOUSE_PASSWORD>"
      }
    }
  }
}

Codex~/.codex/config.toml

[mcp_servers.clickhouse]
command = "uv"
args = ["run", "--with", "mcp-clickhouse", "--python", "3.12", "mcp-clickhouse"]

[mcp_servers.clickhouse.env]
CLICKHOUSE_HOST = "<CLICKHOUSE_HOST>"
CLICKHOUSE_USER = "<CLICKHOUSE_USER>"
CLICKHOUSE_PASSWORD = "<CLICKHOUSE_PASSWORD>"

Gemini CLITerminal

gemini mcp add --scope user -e CLICKHOUSE_HOST=<CLICKHOUSE_HOST> -e CLICKHOUSE_USER=<CLICKHOUSE_USER> -e CLICKHOUSE_PASSWORD=<CLICKHOUSE_PASSWORD> clickhouse uv -- run --with mcp-clickhouse --python 3.12 mcp-clickhouse

Settings 12

`CLICKHOUSE_HOST`	Required: Hostname of the ClickHouse server.
`CLICKHOUSE_USER`	Required: ClickHouse user to connect as; use a least-privilege user.
`CLICKHOUSE_PASSWORD`	Required: Password for that user; not needed when a client certificate is used in mutual TLS mode.
`CLICKHOUSE_PORT`	Optional: HTTP interface port; 8443 when secure, 8123 otherwise.
`CLICKHOUSE_SECURE`	Optional: Use HTTPS to reach ClickHouse; default true.
`CLICKHOUSE_DATABASE`	Optional: Default database for queries.
`CLICKHOUSE_ROLE`	Optional: ClickHouse role to use, if the user needs one.
`CLICKHOUSE_ALLOW_WRITE_ACCESS`	Optional: Set true to allow inserts and DDL; default false (read-only).
`CLICKHOUSE_ALLOW_DROP`	Optional: Set true, with write access, to allow DROP, TRUNCATE, DELETE and UPDATE.
`CLICKHOUSE_MCP_QUERY_TIMEOUT`	Optional: Query timeout in seconds; default 30.
`CHDB_ENABLED`	Optional: Set true to add the chDB tool; needs the mcp-clickhouse[chdb] extra.
`CLICKHOUSE_MCP_SERVER_TRANSPORT`	Optional: stdio (default), http or sse; http/sse need CLICKHOUSE_MCP_AUTH_TOKEN or another auth setting.

What it does

ClickHouse's own MCP server connects an assistant to a ClickHouse cluster over the database's HTTP interface. Out of the box it gives three tools: one lists databases, one pages through the tables in a database with their columns and CREATE statements, and one runs SQL. The SQL tool also accepts DESCRIBE and EXPLAIN ESTIMATE, so a query's output columns or its estimated reads can be checked before it runs. Values can be bound to ClickHouse {name:Type} placeholders through a separate params object instead of being pasted into the SQL.

By default every query runs with ClickHouse's readonly=1 setting. CLICKHOUSE_ALLOW_WRITE_ACCESS=true allows inserts and non-destructive DDL. DROP, TRUNCATE, DELETE, UPDATE and similar statements also need CLICKHOUSE_ALLOW_DROP=true. Queries time out after 30 seconds by default, and the server then tries to cancel them with KILL QUERY.

With the chdb extra installed and CHDB_ENABLED=true, it adds a fourth tool, run_chdb_select_query, and a chdb_initial_prompt prompt. These run SQL in chDB, an in-process ClickHouse engine that can read files and URLs without a server. If chDB is switched on but the extra is missing, the v0.7.0 code (mcp_clickhouse/mcp_server.py) only logs a warning and leaves the tool out, so the tool may be missing without any startup error. Setting CLICKHOUSE_ENABLED=false removes the three ClickHouse tools for a chDB-only setup.

It speaks stdio by default. It can also serve Streamable HTTP or the deprecated SSE transport, with a bearer token or a FastMCP OAuth/OIDC provider in front.

What it needs

Runtime	Python 3.10+

Python 3.10 to 3.14, with 3.12 recommended. The documented launch command uses uv. You need a ClickHouse server reachable over its HTTP interface (8123/8443, not the native 9000/9440 ports) and a ClickHouse user and password. ClickHouse's public SQL Playground works with the demo user. chDB needs the mcp-clickhouse[chdb] extra and no server.

Limits

Only ClickHouse's HTTP interface is supported; native-protocol ports fail. Writes are off unless CLICKHOUSE_ALLOW_WRITE_ACCESS=true. The extra CLICKHOUSE_ALLOW_DROP check is described as a best-effort guard in the server, not a security boundary. Queries time out after 30 s by default (CLICKHOUSE_MCP_QUERY_TIMEOUT). list_tables returns 50 tables per page by default. ClickHouse Cloud does not accept X.509 client certificates. Over HTTP/SSE, startup fails unless a token, an OAuth provider or explicitly disabled auth is configured. The SSE transport is deprecated.

Who it suits

It suits developers and analysts who run ClickHouse, whether self-hosted or ClickHouse Cloud, and want an assistant to explore schemas and run analytical SQL. Because the default is read-only, it is a reasonable first connection to a production cluster when paired with a least-privilege ClickHouse user. chDB mode suits ad-hoc SQL over local files without a database server. Teams that need writes must turn them on and should restrict grants in ClickHouse itself. For other databases, pick a server built for them.

Tools 4

list_databases: Lists the databases on the connected ClickHouse server.
list_tables: Pages through a database's tables with column details, filtered by LIKE/NOT LIKE patterns.
run_query: Runs SQL, with optional named parameters; read-only unless write access is turned on.
run_chdb_select_query: Runs SQL in the embedded chDB engine; present only when chDB is enabled and installed.

Popularity

82 popularity score, on our list (the bar is 36)

★ 903 ↓ 241k/mo

GitHub stars	903	35.5 points
PyPI downloads, last month	240,897	38.2 points
Official server	Yes	8 points

Measured 2026-11-07. How the score works.

Where it is published

Code	clickhouse/mcp-clickhouse ★ 903
PyPI	mcp-clickhouse

What it can reach

Runs	On your machine
Reaches	A database, The internet, Files on your machine
Changes things	Yes: it can write, send, create or delete
Sign-in	Account credentials
Licence	Apache-2.0 (GitHub)
Last code change	2026-11-04

Connects to the ClickHouse server you configure with the ClickHouse user and password you give it. What it can touch is whatever that user's grants allow. The server runs on your machine. Queries are read-only by default (readonly=1). Turning on CLICKHOUSE_ALLOW_WRITE_ACCESS allows writes, and CLICKHOUSE_ALLOW_DROP adds destructive statements. The makers say the drop check is not a security boundary and advise a dedicated least-privilege user. chDB mode can read local files and URLs. Over HTTP/SSE the /health endpoint is unauthenticated, and auth can be switched off with CLICKHOUSE_MCP_AUTH_DISABLED, which the docs reserve for local development. A .env file found from the package directory upward is trusted for auth settings.

Over time

GitHub stars 903 +16 (+2 %)

903887

14 Oct 20267 Nov 2026

PyPI downloads a month 241k +42k (+21 %)

261k139k

12 May 20267 Nov 2026

Before the site measured it, read from pypistats' daily download counts.

Popularity score 82 +0

8282

14 Oct 20267 Nov 2026

What is rising across the directory

Sources

Page checked 2026-10-14.

Badge for your README

Shows this server's rank in its category, and stars for a server that runs on your machine. It updates every hour.

MarkdownREADME.md

[![ClickHouse MCP Server on EveryMCPServer](https://everymcpserver.com/badge/clickhouse.svg)](https://everymcpserver.com/servers/clickhouse)

Connect your client

Add in one click

Or add it by command or config

Settings 12

What it does

What it needs

Limits

Who it suits

Tools 4

Similar servers

hypequery MCP server

dbt MCP Server

Metabase MCP server

MySQL MCP Server

MCPQL

Dremio MCP Server