ClickHouse MCP Server

Official ClickHouse MCP server for natural language SQL querying of ClickHouse clusters and chDB embedded instances, with read-only mode by default.

Database by ClickHouse Basic Auth (ClickHouse user/password); Bearer Token or OAuth for HTTP/SSE transports active

GitHub Docs

Overview

The ClickHouse MCP server is the official Model Context Protocol implementation maintained by ClickHouse. It lets AI agents like Claude connect to a ClickHouse cluster (self-hosted or ClickHouse Cloud) or a chDB embedded instance and execute SQL queries through a small, focused set of tools. Queries run in read-only mode by default, with explicit opt-in environment variables required to enable writes, DDL, or destructive operations like DROP and TRUNCATE.

The server exposes four tools: list databases, list tables (with pagination and filtering), run a SQL query against the configured ClickHouse server, and run a SQL query against an embedded chDB engine. This is enough surface area for analytical workflows where an agent needs to discover schemas, inspect tables, and run aggregations on large event datasets without giving up control over mutations.

It is distributed as a Python package (mcp-clickhouse) and supports stdio, HTTP, and SSE transports. HTTP and SSE deployments support static bearer tokens or OAuth/OIDC via FastMCP, so the same server can run locally for desktop clients or be hosted behind an auth layer for team use.

Tools

Tool	Description
`run_query`	Execute a SQL query against the configured ClickHouse cluster. Read-only by default; writes require CLICKHOUSE_ALLOW_WRITE_ACCESS=true.
`list_databases`	List all databases available on the connected ClickHouse cluster.
`list_tables`	List tables in a database with optional LIKE/NOT LIKE filters, pagination, and detailed column metadata.
`run_chdb_select_query`	Execute a SQL query using the chDB embedded ClickHouse engine (requires the [chdb] extra).

Setup Guide

Prerequisites

Python 3.10 or higher
uv package manager (recommended) or pip
A ClickHouse instance you can reach over the network, or chDB for embedded use
ClickHouse host, user, and password

Install

python3 -m pip install mcp-clickhouse

To use the embedded chDB tool, install with the extra:

python3 -m pip install "mcp-clickhouse[chdb]"

Claude Desktop config

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%/Claude/claude_desktop_config.json (Windows). Replace uv with the absolute path from which uv if Claude Desktop cannot find it.

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.10",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_PORT": "8443",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
      }
    }
  }
}

Environment variables

Required:

CLICKHOUSE_HOST: ClickHouse server hostname
CLICKHOUSE_USER: Username
CLICKHOUSE_PASSWORD: Password

Optional:

CLICKHOUSE_PORT: Defaults to 8443 (HTTPS) or 8123 (HTTP)
CLICKHOUSE_SECURE: "true" to use HTTPS (default)
CLICKHOUSE_DATABASE: Default database
CLICKHOUSE_ALLOW_WRITE_ACCESS: "true" to allow writes/DDL (default "false")
CLICKHOUSE_ALLOW_DROP: "true" to allow DROP/TRUNCATE (default "false")
CLICKHOUSE_MCP_SERVER_TRANSPORT: stdio (default), http, or sse

For HTTP/SSE deployments you can set CLICKHOUSE_MCP_AUTH_TOKEN for a static bearer token, configure OAuth/OIDC via FASTMCP_SERVER_AUTH, or set CLICKHOUSE_MCP_AUTH_DISABLED=true for local development only.

After saving the config, restart Claude Desktop.

Use Cases

Let an agent discover the schema of a ClickHouse Cloud project by listing databases and tables, then run ad-hoc analytical queries against large event tables
Run product analytics queries (DAU, retention cohorts, funnels) in natural language against a ClickHouse warehouse without writing SQL by hand
Use chDB locally to query CSV, Parquet, or other files as if they were ClickHouse tables, without standing up a server
Power a read-only data assistant for non-engineers: writes and DROPs are disabled by default, so accidental mutations are blocked at the server level
Host the server over HTTP with a bearer token or OAuth so a team of agents can share a single configured ClickHouse connection

Example Prompts

"List all databases in our ClickHouse cluster, then show me the tables in the events database."
"Query the pageviews table for the top 10 referrers by unique users in the last 7 days."
"Describe the columns of orders and write a query that computes weekly revenue by country."
"Using chDB, read ./logs/*.parquet and count rows grouped by status code."
"Run an EXPLAIN on this query and suggest indexes or projections that could speed it up."

Pros

Officially maintained by ClickHouse, so it tracks the database closely
Safe defaults: read-only mode, with separate flags for writes and for DROP/TRUNCATE
Supports both a remote ClickHouse cluster and the embedded chDB engine from the same server
Multiple transports (stdio, HTTP, SSE) with bearer token and OAuth options for hosted deployments

Limitations

Small tool surface: only query and schema listing, no first-class helpers for inserts, materialized views, or cluster admin
Requires Python 3.10+ and uv for the recommended install path
HTTP/SSE auth setup (FastMCP OAuth providers) requires extra configuration beyond the basic stdio flow

Alternatives

Altinity/altinity-mcp: community ClickHouse MCP server with OAuth 2.0, JWE, and TLS support
oualib/chmcp: community server that adds ClickHouse Cloud management APIs alongside query tools
Generic SQL MCP servers (Postgres, MySQL, DuckDB) if you are not specifically on ClickHouse