MCP Clickhouse

An MCP server designed for ClickHouse, providing database query and management functions

Database Developer tools #Database Query #ClickHouse #Data Management #MCP Service .Python

rating : 2.5 points

downloads : 15

update time : 2025-04-28

What is the ClickHouse MCP Server?

The ClickHouse MCP Server is a lightweight tool for securely executing SQL queries and managing database tables on a ClickHouse database. It provides a convenient data access interface through the Model Context Protocol (MCP).

How to use the ClickHouse MCP Server?

You can set up and run the ClickHouse MCP Server in just a few steps. You can execute SQL queries, list databases and tables through a simple command-line tool.

Use Cases

Suitable for enterprises and developers who need to quickly access and analyze ClickHouse databases, such as data analysis, report generation, and real-time monitoring.

Main Features

Execute SQL QueriesSecurely execute read-only SQL queries to ensure that operations do not affect the database.

List All DatabasesEasily view all databases in the ClickHouse cluster.

List TablesList all tables in the specified database.

Advantages and Limitations

Advantages

Easy to install and configure

Supports secure read-only queries

Deeply integrated with ClickHouse

Limitations

Only supports read-only queries

Requires a ClickHouse server environment

How to Use

Install Dependencies

Run the `uv sync` command to install the required dependencies. If you haven't installed `uv`, please refer to the official documentation for installation.

Configure Environment Variables

Add the ClickHouse connection information to the `.env.production` file.

Start the MCP Server

Use the `fastmcp install` command to start the MCP server.

Usage Examples

Query the Users TableExecute an SQL query to get the first 10 records from the users table.

List All DatabasesGet a list of all databases in the ClickHouse cluster.

Frequently Asked Questions

How to ensure the security of queries?

Does it support multi-node clusters?

How to uninstall the MCP Server?

Related Resources

ClickHouse Official Documentation

Gain in-depth knowledge of the basics and advanced features of ClickHouse.

GitHub Code Repository

Get the latest code and examples.

Installation Guide

Learn how to install and configure the `uv` tool.

🚀 ClickHouse MCP Server

The ClickHouse MCP Server provides a set of tools to interact with ClickHouse clusters, enabling operations such as query execution, database listing, and table listing.

🚀 Quick Start

Prerequisites

Install uv following the instructions here.
Have a ClickHouse cluster ready.

Steps

Run uv sync to install dependencies, then execute source .venv/bin/activate.
Set up the .env.production file with ClickHouse credentials:

CLICKHOUSE_HOST=<CLICKHOUSE_HOST>
CLICKHOUSE_PORT=<CLICKHOUSE_PORT>
CLICKHOUSE_USER=<CLICKHOUSE_USER>
CLICKHOUSE_PASSWORD=<CLICKHOUSE_PASSWORD>

Run fastmcp install mcp_clickhouse/mcp_server.py -f .env.production to install the server.
Restart Claude Desktop.

✨ Features

Tools

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

📦 Installation

⚠️ Important Note

This is a temporary configuration process and will be significantly improved once the package is released.

Run uv sync to install dependencies. To install uv, follow the instructions here. Then execute source .venv/bin/activate.
Set up the .env.production file with ClickHouse credentials:

CLICKHOUSE_HOST=<CLICKHOUSE_HOST>
CLICKHOUSE_PORT=<CLICKHOUSE_PORT>
CLICKHOUSE_USER=<CLICKHOUSE_USER>
CLICKHOUSE_PASSWORD=<CLICKHOUSE_PASSWORD>

Run fastmcp install mcp_clickhouse/mcp_server.py -f .env.production to install the server.
Restart Claude Desktop.

🔧 Technical Details

Development

Run docker compose up -d in the test-services directory to start the ClickHouse cluster.
Add the following variables to the .env file in the root directory:

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

Run uv sync to install dependencies. To install uv, follow the instructions here. Then execute source .venv/bin/activate.
For convenient testing, run fastmcp dev mcp_clickhouse/mcp_server.py to start the MCP server.