ClickHouse

by ClickHouse

v0.4.1

Repository Docs

Databases & Data

databaseanalyticsolapsql

Summary

ClickHouse's official MCP server — run analytical SQL, explore schemas, and query local files with chDB.

Features

Run analytical SQL against ClickHouse from an AI client
List databases and inspect table schemas
Includes chDB for querying local files without a server

Installation

Set up this MCP server in your favorite AI agent — copy a ready-made configuration below.

Any MCP-compatible agent

Most agents (Claude, Cursor, Windsurf, VS Code, and more) read a standard mcpServers configuration.

Open your agent's MCP configuration file.
Merge the snippet below into it, filling in the environment variables with your own values.
Restart the agent — the "ClickHouse" tools will be available.

{
  "mcpServers": {
    "clickhouse": {
      "command": "uvx",
      "args": [
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "localhost",
        "CLICKHOUSE_USER": "default",
        "CLICKHOUSE_PASSWORD": ""
      }
    }
  }
}

Claude Code

Add the server with a single CLI command.

claude mcp add clickhouse -e CLICKHOUSE_HOST=localhost -e CLICKHOUSE_USER=default -e CLICKHOUSE_PASSWORD= -- uvx mcp-clickhouse

Claude Desktop

Add the server to claude_desktop_config.json (Settings → Developer → Edit Config).

{
  "mcpServers": {
    "clickhouse": {
      "command": "uvx",
      "args": [
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "localhost",
        "CLICKHOUSE_USER": "default",
        "CLICKHOUSE_PASSWORD": ""
      }
    }
  }
}

Cursor

{
  "command": "uvx",
  "args": [
    "mcp-clickhouse"
  ],
  "env": {
    "CLICKHOUSE_HOST": "localhost",
    "CLICKHOUSE_USER": "default",
    "CLICKHOUSE_PASSWORD": ""
  }
}

Windsurf

{
  "command": "uvx",
  "args": [
    "mcp-clickhouse"
  ],
  "env": {
    "CLICKHOUSE_HOST": "localhost",
    "CLICKHOUSE_USER": "default",
    "CLICKHOUSE_PASSWORD": ""
  }
}

VS Code

{
  "command": "uvx",
  "args": [
    "mcp-clickhouse"
  ],
  "env": {
    "CLICKHOUSE_HOST": "localhost",
    "CLICKHOUSE_USER": "default",
    "CLICKHOUSE_PASSWORD": ""
  }
}

Description

ClickHouse's official MCP server lets an assistant query a ClickHouse instance directly, which turns "what happened to conversion last week" into a real query against real data rather than a guess.

What it provides

SQL execution against your ClickHouse cluster, with results returned in a form the model can reason about
Schema discovery — list databases and tables, inspect column types, and understand partitioning before writing a query
chDB support for running ClickHouse SQL over local files (Parquet, CSV, JSON) with no server at all, which is remarkably useful for ad-hoc analysis
ClickHouse Cloud compatibility alongside self-managed deployments

Practical notes

Queries execute with the permissions of the configured user, so point it at a read-only account unless you have a specific reason not to. Query limits and timeouts are configurable to prevent an over-enthusiastic assistant from running a scan across a billion rows.

Installed with uvx mcp-clickhouse and configured through environment variables for host, user, and password.

Related MCP Servers

Featured

DBHub

by Bytebase

A universal database MCP server — one integration for PostgreSQL, MySQL, SQL Server, SQLite, and MariaDB.

Databases & Data

databasesqlmulti-database

Featured

MongoDB

by MongoDB

MongoDB's official MCP server — query databases, explore schemas, and manage Atlas clusters from an AI client.

Databases & Data

databasenosqlmongodb

Upstash Redis

by Upstash

Run Redis commands against Upstash's serverless Redis over HTTP, with documentation search built in.

Databases & Data

redisserverlesscache

dbt

by dbt Labs

dbt Labs' official MCP server — explore project metadata, run dbt commands, and query the Semantic Layer.

Databases & Data

datadbtanalytics

Browse all MCP servers →