clickhouse_mcp_ MCP Server

Use This MCP server To

Execute SQL queries on ClickHouse databases via AI assistants List and explore database tables securely Retrieve and analyze data for real-time AI insights Enable controlled database access for AI-driven applications Integrate ClickHouse data into AI-enhanced workflows Support multi-step reasoning with live database context

README

ClickHouse MCP Server

A Model Context Protocal (MCP) server implement for ClickHouse.

This server provides AI assistants with a secure and structured way to explore and analyze databases. It enables them to list tables, read data, and execute SQL queries through a controlled interface, ensuring responsible database access.

Configuration

Set the following environment variables:

CLICKHOUSE_HOST=localhost    
CLICKHOUSE_PORT=8123         
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=CHANGE_TO_YOUR_PASSWORD
CLICKHOUSE_DATABASE=default

Or via command-line args:

--host the database host
--port the database port
--user the database username
--password the database password
--database the database name

Usage

Fake some data in clickhouse

Check the SQL in dev_contribute.md for details.

Post your question to AI assistant in Cline

What is the sales volume in each region? Which product is the best - selling?

Demo Screenshot

CLINE

Configure the MCP server in VSCode, Cline extension, or other MCP client.: Example:

{
  "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"
      }
    }
    
  }
}

License

APACHE - See LICENSE file for details.

Contribute

See dev_contribute.md for details.

Prerequisites

Python with uv package manager
ClickHouse installation
MCP server dependencies

Acknowledgement

This library's implementation was inspired by the following three repositories and incorporates their code, respect for the open-source spirit!

Thanks!

clickhouse_mcp_server FAQ

How do I configure the ClickHouse MCP Server?

Set environment variables like CLICKHOUSE_HOST, CLICKHOUSE_PORT, CLICKHOUSE_USER, CLICKHOUSE_PASSWORD, and CLICKHOUSE_DATABASE or use command-line arguments to configure the server.

Can the ClickHouse MCP Server execute arbitrary SQL queries?

Yes, it allows executing SQL queries through a controlled interface to ensure secure and responsible database access.

Is the ClickHouse MCP Server compatible with multiple AI models?

Yes, it is designed to work with various LLM providers such as OpenAI, Claude, and Gemini by exposing structured database context.

How does the server ensure secure database access?

It uses controlled interfaces and configuration settings to restrict and monitor query execution, preventing unauthorized access.

Can I use the ClickHouse MCP Server for real-time data analysis?

Yes, it supports live querying and data retrieval to enable real-time AI-driven insights and workflows.

What kind of data operations can AI assistants perform via this server?

AI assistants can list tables, read data, and execute SQL queries within the configured ClickHouse database.

How do I start using the ClickHouse MCP Server with an AI assistant?

Configure the server with your database credentials, then connect your AI assistant to send natural language queries that translate into SQL commands.

Does the server support multi-tenant or multi-database setups?

Configuration is flexible to connect to different databases, but multi-tenant support depends on deployment and access control setup.