ClickHouse

by headcrab

Not rated

GitHub

About

Connects Claude to ClickHouse databases for direct query execution and data retrieval from time-series data, analytics datasets, or large-scale data warehouses without leaving the conversation interface.

Details

Author: headcrab
Repository: Headcrab/clickhouse-mcp
License: MIT License
Categories: Productivity, Developer Tools, Design, AI, Search, Database, Frontend, Infrastructure, Security

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below
Plugin Name ClickHouse

Command (node, npx, python, etc.) /path/to/clickhouse-mcp
Arguments
- Argument 1 -transport
- Argument 2 stdio
- Argument 3 -url
- Argument 4 localhost:9000/default
- Argument 5 -user
- Argument 6 default
- Argument 7 -password
- Argument 8 clickhouse
Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "clickhouse": {
            "env": {},
            "args": [
                "-transport",
                "stdio",
                "-url",
                "localhost:9000/default",
                "-user",
                "default",
                "-password",
                "clickhouse"
            ],
            "command": "/path/to/clickhouse-mcp"
        }
    }
}

JSON

{
    "mcpServers": {
        "clickhouse": {
            "env": {},
            "args": [
                "/c",
                "/path/to/clickhouse-mcp",
                "-transport",
                "stdio",
                "-url",
                "localhost:9000/default",
                "-user",
                "default",
                "-password",
                "clickhouse"
            ],
            "command": "cmd"
        }
    }
}

JSON

{
    "mcpServers": {
        "clickhouse": {
            "env": {},
            "args": [
                "-transport",
                "stdio",
                "-url",
                "localhost:9000/default",
                "-user",
                "default",
                "-password",
                "clickhouse"
            ],
            "command": "/path/to/clickhouse-mcp"
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "clickhouse": {
            "env": {},
            "args": [
                "-transport",
                "stdio",
                "-url",
                "localhost:9000/default",
                "-user",
                "default",
                "-password",
                "clickhouse"
            ],
            "command": "/path/to/clickhouse-mcp"
        }
    }
}

JSON

{
    "mcpServers": {
        "clickhouse": {
            "env": {},
            "args": [
                "/c",
                "/path/to/clickhouse-mcp",
                "-transport",
                "stdio",
                "-url",
                "localhost:9000/default",
                "-user",
                "default",
                "-password",
                "clickhouse"
            ],
            "command": "cmd"
        }
    }
}

JSON

{
    "mcpServers": {
        "clickhouse": {
            "env": {},
            "args": [
                "-transport",
                "stdio",
                "-url",
                "localhost:9000/default",
                "-user",
                "default",
                "-password",
                "clickhouse"
            ],
            "command": "/path/to/clickhouse-mcp"
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "clickhouse": {
            "env": {},
            "args": [
                "-transport",
                "stdio",
                "-url",
                "localhost:9000/default",
                "-user",
                "default",
                "-password",
                "clickhouse"
            ],
            "command": "/path/to/clickhouse-mcp"
        }
    }
}

JSON

{
    "mcpServers": {
        "clickhouse": {
            "env": {},
            "args": [
                "/c",
                "/path/to/clickhouse-mcp",
                "-transport",
                "stdio",
                "-url",
                "localhost:9000/default",
                "-user",
                "default",
                "-password",
                "clickhouse"
            ],
            "command": "cmd"
        }
    }
}

JSON

{
    "mcpServers": {
        "clickhouse": {
            "env": {},
            "args": [
                "-transport",
                "stdio",
                "-url",
                "localhost:9000/default",
                "-user",
                "default",
                "-password",
                "clickhouse"
            ],
            "command": "/path/to/clickhouse-mcp"
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "clickhouse": {
            "env": {},
            "args": [
                "-transport",
                "stdio",
                "-url",
                "localhost:9000/default",
                "-user",
                "default",
                "-password",
                "clickhouse"
            ],
            "command": "/path/to/clickhouse-mcp"
        }
    }
}

JSON

{
    "mcpServers": {
        "clickhouse": {
            "env": {},
            "args": [
                "/c",
                "/path/to/clickhouse-mcp",
                "-transport",
                "stdio",
                "-url",
                "localhost:9000/default",
                "-user",
                "default",
                "-password",
                "clickhouse"
            ],
            "command": "cmd"
        }
    }
}

JSON

{
    "mcpServers": {
        "clickhouse": {
            "env": {},
            "args": [
                "-transport",
                "stdio",
                "-url",
                "localhost:9000/default",
                "-user",
                "default",
                "-password",
                "clickhouse"
            ],
            "command": "/path/to/clickhouse-mcp"
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "clickhouse": {
            "env": {},
            "args": [
                "-transport",
                "stdio",
                "-url",
                "localhost:9000/default",
                "-user",
                "default",
                "-password",
                "clickhouse"
            ],
            "command": "/path/to/clickhouse-mcp"
        }
    }
}

JSON

{
    "mcpServers": {
        "clickhouse": {
            "env": {},
            "args": [
                "/c",
                "/path/to/clickhouse-mcp",
                "-transport",
                "stdio",
                "-url",
                "localhost:9000/default",
                "-user",
                "default",
                "-password",
                "clickhouse"
            ],
            "command": "cmd"
        }
    }
}

JSON

{
    "mcpServers": {
        "clickhouse": {
            "env": {},
            "args": [
                "-transport",
                "stdio",
                "-url",
                "localhost:9000/default",
                "-user",
                "default",
                "-password",
                "clickhouse"
            ],
            "command": "/path/to/clickhouse-mcp"
        }
    }
}

`get_databases`

Retrieve a list of databases.

`get_tables`

Retrieve a list of tables in a specified database. Parameters: database (string)

`get_schema`

Retrieve the schema of a specified table in a specified database. Parameters: database (string), table (string)

`query`

Execute an SQL query. Parameters: query (string), limit (optional integer)

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "clickhouse": {
            "env": {},
            "args": [
                "-transport",
                "stdio",
                "-url",
                "localhost:9000/default",
                "-user",
                "default",
                "-password",
                "clickhouse"
            ],
            "command": "/path/to/clickhouse-mcp"
        }
    }
}

Linux

{
    "env": [],
    "args": [
        "-transport",
        "stdio",
        "-url",
        "localhost:9000/default",
        "-user",
        "default",
        "-password",
        "clickhouse"
    ],
    "command": "/path/to/clickhouse-mcp"
}

Macos

{
    "env": [],
    "args": [
        "-transport",
        "stdio",
        "-url",
        "localhost:9000/default",
        "-user",
        "default",
        "-password",
        "clickhouse"
    ],
    "command": "/path/to/clickhouse-mcp"
}

Windows

{
    "env": [],
    "args": [
        "/c",
        "/path/to/clickhouse-mcp",
        "-transport",
        "stdio",
        "-url",
        "localhost:9000/default",
        "-user",
        "default",
        "-password",
        "clickhouse"
    ],
    "command": "cmd"
}

ClickHouse MCP Server

Нормальный MCP-сервер для ClickHouse с безопасными дефолтами, stdio и SSE, Docker-запуском и read-only режимом по умолчанию.

Что умеет

- показать список баз данных;
- показать таблицы в базе;
- показать схему таблицы;
- выполнить SQL через MCP-инструмент query;
- работать через stdio и SSE;
- запускаться локально, в Docker и в docker compose.

Что важно про безопасность

- По умолчанию сервер работает в read-only режиме.
- INSERT, ALTER, CREATE, DROP, TRUNCATE, RENAME, OPTIMIZE, SYSTEM, GRANT, REVOKE и другие write/admin запросы запрещены, пока не включен --allow-write.
- Для SELECT без LIMIT сервер сам добавляет лимит по умолчанию.
- --secure теперь реально включает TLS с проверкой сертификата.
- Если нужен небезопасный TLS для dev/self-host, включайте отдельно --insecure-skip-verify.

Быстрый старт

Сборка

go build -o clickhouse-mcp

Запуск через stdio

./clickhouse-mcp \
  -transport stdio \
  -url localhost:9000/default \
  -user default \
  -password clickhouse

Запуск через SSE

./clickhouse-mcp \
  -transport sse \
  -port 8082 \
  -public-base-url http://localhost:8082 \
  -url localhost:9000/default \
  -user default \
  -password clickhouse

Тестовый режим

./clickhouse-mcp -test

Он печатает реальные примеры tools/call, которые можно слать MCP-клиенту.

Docker

Один контейнер

docker build -t clickhouse-mcp .

docker run --rm -p 8082:8082 \ -e CLICKHOUSE_MCP_TRANSPORT=sse \ -e CLICKHOUSE_MCP_PORT=8082 \ -e CLICKHOUSE_MCP_PUBLIC_BASE_URL=http://localhost:8082 \ -e CLICKHOUSE_MCP_URL=host.docker.internal:9000/default \ -e CLICKHOUSE_MCP_USER=default \ -e CLICKHOUSE_MCP_PASSWORD=clickhouse \ clickhouse-mcp

Если ClickHouse стоит на хосте Linux, добавьте --add-host=host.docker.internal:host-gateway.
Для Docker-сценариев у default должен быть задан пароль: без него официальный образ ClickHouse режет сетевой доступ к этому пользователю.

Docker Compose

docker compose up -d

По умолчанию compose поднимает:

- clickhouse на 9000 и 8123;
- clickhouse-mcp на 8082.
- логин ClickHouse: default
- пароль ClickHouse: clickhouse

Healthcheck MCP:

```text

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Jump to

Setting up with Highlight

get_databases

get_tables

get_schema

query

Claude Desktop / Cursor

Linux

Macos

Windows

ClickHouse MCP Server

Что умеет

Что важно про безопасность

Быстрый старт

Сборка

Запуск через stdio

Запуск через SSE

Тестовый режим

Docker

Один контейнер

Docker Compose

Install

More like this

Time

Sentry

Github

Git

GitLab

Context 7

`get_databases`

`get_tables`

`get_schema`

`query`