📌Overview

Purpose: To provide an efficient and safe interface for executing SQL queries on ClickHouse databases through an MCP server.

Overview: The ClickHouse MCP Server is designed to facilitate interaction with ClickHouse clusters, enabling users to run SQL queries and manage database resources with ease and security.

Key Features:

Run Select Query: Allows users to execute SQL queries on the ClickHouse cluster in a read-only mode, ensuring safety while retrieving data.
List Databases: Provides the ability to list all available databases within the ClickHouse cluster, aiding users in understanding the structure of their data environment.
List Tables: Enables users to retrieve a list of tables within a specified database, simplifying navigation and access to relevant data structures.

ClickHouse MCP Server

An MCP server for ClickHouse.

Features

Tools

run_select_query
- Execute SQL queries on your ClickHouse cluster.
- Input: sql (string): The SQL query to execute.
- All ClickHouse queries are run with readonly = 1 to ensure they are safe.
list_databases
- List all databases on your ClickHouse cluster.
list_tables
- List all tables in a database.
- Input: database (string): The name of the database.

Configuration

Open the Claude Desktop configuration file located at:
- On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- On Windows: %APPDATA%/Claude/claude_desktop_config.json
Add the following configuration, updating environment variables to point to your ClickHouse service:

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

Alternatively, to try it out with the ClickHouse SQL Playground, use:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.13",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
        "CLICKHOUSE_PORT": "8443",
        "CLICKHOUSE_USER": "demo",
        "CLICKHOUSE_PASSWORD": "",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
      }
    }
  }
}

Locate the command entry for uv and replace it with the absolute path to the uv executable (e.g., use which uv on macOS).
Restart Claude Desktop to apply the changes.

Development

In the test-services directory, run docker compose up -d to start the ClickHouse cluster.
Add the following variables to a .env file in the root of the repository.

Note: The default user here is for local development only.

CLICKHOUSE_HOST=localhost
CLICKHOUSE_PORT=8123
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse

Run uv sync to install dependencies. To install uv, follow the instructions at https://docs.astral.sh/uv/. Then activate your environment with source .venv/bin/activate.
For testing, run mcp dev mcp_clickhouse/mcp_server.py to start the MCP server.

Environment Variables

Required Variables

CLICKHOUSE_HOST: Hostname of your ClickHouse server
CLICKHOUSE_USER: Username for authentication
CLICKHOUSE_PASSWORD: Password for authentication

CAUTION
Treat your MCP database user as an external client, granting minimum privileges necessary. Avoid using default or administrative users.

Optional Variables

CLICKHOUSE_PORT: Port of your ClickHouse server
- Default: 8443 if HTTPS enabled, 8123 if disabled
CLICKHOUSE_SECURE: Enable HTTPS connection
- Default: "true"
CLICKHOUSE_VERIFY: Enable SSL certificate verification
- Default: "true"
CLICKHOUSE_CONNECT_TIMEOUT: Connection timeout in seconds
- Default: "30"
CLICKHOUSE_SEND_RECEIVE_TIMEOUT: Send/receive timeout in seconds
- Default: "300"
CLICKHOUSE_DATABASE: Default database to use
- Default: None

Example Configurations

Local Development with Docker:

CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse
CLICKHOUSE_SECURE=false  # Uses port 8123 automatically
CLICKHOUSE_VERIFY=false

ClickHouse Cloud:

CLICKHOUSE_HOST=your-instance.clickhouse.cloud
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=your-password
# CLICKHOUSE_SECURE=true  # Uses port 8443 automatically
# CLICKHOUSE_DATABASE=your_database

ClickHouse SQL Playground:

CLICKHOUSE_HOST=sql-clickhouse.clickhouse.com
CLICKHOUSE_USER=demo
CLICKHOUSE_PASSWORD=
# Uses secure defaults (HTTPS on port 8443)

You can set these variables in your environment, in a .env file, or in the Claude Desktop configuration:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.13",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_DATABASE": "<optional-database>"
      }
    }
  }
}

YouTube Overview

Watch the overview on YouTube:
https://www.youtube.com/watch?v=y9biAm_Fkqw