ClickHouse MCP Server

English | 中文

A Model Context Protocol (MCP) server for ClickHouse database integration.

Features

Connect to ClickHouse databases via HTTP protocol
Support for multiple database instances
Execute queries and retrieve results
Compatible with MCP clients

Available Tools

list_databases - List all databases
list_tables - List all tables in a database
describe_table - Describe a table structure
execute_query - Execute SQL queries (default limit: 100 rows, max: 1000 rows)

Installation

Using Docker

Pull the pre-built image:

docker pull zouweidong/clickhouse-mcp-server

Build from Source

https://github.com/zou-weidong/clickhouse-mcp-server.git
cd clickhouse-mcp-server
docker build -t clickhouse-mcp-server .

Environment Variables

| Variable | Description | Default | Required | |----------|-------------|---------|----------| | CLICKHOUSE_ADDR | ClickHouse server address(es). Use ; to separate multiple addresses | - | Yes | | CLICKHOUSE_DATABASE | Database name to connect to | - | Yes | | CLICKHOUSE_USER | Username for authentication | - | No | | CLICKHOUSE_PASSWORD | Password for authentication | - | No |

Example Configuration

bash export CLICKHOUSE_ADDR=localhost:8123 export CLICKHOUSE_DATABASE=my_database export CLICKHOUSE_USER=default export CLICKHOUSE_PASSWORD=your_password

Multiple Servers

bash export CLICKHOUSE_ADDR=server1:8123;server2:8123;server3:8123

Usage

Run with Docker:

docker run -e CLICKHOUSE_ADDR=localhost:8123 \
        -e CLICKHOUSE_DATABASE=my_db \
        -e CLICKHOUSE_USER=default \
        -e CLICKHOUSE_PASSWORD=password \
        zouweidong/clickhouse-mcp-server

Protocol

Uses HTTP protocol to communicate with ClickHouse by default.

License

MIT License - see LICENSE file for details.

MCP Servers