home / mcp / clickhouse mcp server

ClickHouse MCP Server

Provides an MCP server to securely explore ClickHouse databases by listing tables, reading data, and running SQL queries through a controlled interface.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "dubin555-clickhouse_mcp_server": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/clickhouse_mcp_server",
        "run",
        "-m",
        "clickhouse_mcp_server.server"
      ],
      "env": {
        "CLICKHOUSE_HOST": "localhost",
        "CLICKHOUSE_PORT": "8123",
        "CLICKHOUSE_USER": "default",
        "CLICKHOUSE_DATABASE": "default",
        "CLICKHOUSE_PASSWORD": "CHANGE_TO_YOUR_PASSWORD"
      }
    }
  }
}

You can use this MCP server to securely explore and analyze ClickHouse databases through a structured, controlled interface. It lets AI assistants list tables, read data, and execute SQL queries against ClickHouse with clearly defined environment settings and run configurations.

How to use

Connect to your ClickHouse MCP server from an MCP client (such as CLINE or another compatible tool). You configure the server to talk to ClickHouse and then issue natural language questions or SQL-like prompts to retrieve data, run queries, or inspect table structures. Examples of questions you might ask include things like: What is the sales volume in each region? Which product is the best-selling?

How to install

Prerequisites you need before running the server:

Python with the uv package manager
ClickHouse installation
MCP server dependencies

Install and run steps you can follow to start the MCP server for ClickHouse:

# Set up environment variables for ClickHouse connection
export CLICKHOUSE_HOST=localhost
export CLICKHOUSE_PORT=8123
export CLICKHOUSE_USER=default
export CLICKHOUSE_PASSWORD=CHANGE_TO_YOUR_PASSWORD
export CLICKHOUSE_DATABASE=default

# Run the MCP server via the CLI (example command shown in configuration)
# The command assumes you have the MCP server code at the specified directory
uv --directory /path/to/clickhouse_mcp_server run -m clickhouse_mcp_server.server

Additional sections

Configuration, security considerations, and practical usage notes help you get the most out of the ClickHouse MCP Server.

Environment variables required to connect to ClickHouse are provided in the server configuration. You can set them in your shell or in your MCP client’s environment configuration.

Example MCP client configuration snippet demonstrates how to start the local MCP server with the necessary environment settings.

{
  "mcpServers": {
    "clickhouse": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/clickhouse_mcp_server",
        "run",
        "-m",
        "clickhouse_mcp_server.server"
      ],
      "env": {
        "CLICKHOUSE_HOST": "localhost",
        "CLICKHOUSE_PORT": "8123",
        "CLICKHOUSE_USER": "default",
        "CLICKHOUSE_PASSWORD": "CHANGE_TO_YOUR_PASSWORD",
        "CLICKHOUSE_DATABASE": "default"
      }
    }
  }
}

Available tools

list_tables

Lists all tables available in the connected ClickHouse database.

read_data

Reads data from a specified table or query result set.

execute_sql

Executes a given SQL query against ClickHouse and returns results.