ClickHouse

A MCP server for ClickHouse

python

2

GitHub Stars

python

Language

4 months ago

First Indexed

3 weeks ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "thomaub-clickhouse_mcp_server": {
      "command": "python",
      "args": [
        "clickhouse_mcp_server/server.py"
      ]
    }
  }
}

You can run a dedicated MCP server that exposes ClickHouse databases, tables, schemas, and query execution to AI applications. This enables you to integrate ClickHouse as a data source for LLMs and automated workflows with secure, protocol-based communication.

How to use

You connect to the ClickHouse MCP Server with your MCP client to discover resources, inspect table schemas, and run SELECT queries. The server exposes ClickHouse databases and tables as resources, lets you retrieve schemas, and supports executing queries against your ClickHouse instance. Use it to feed structured data to your AI models, validate results, and build data-driven prompts and tools.

How to install

Prerequisites you need before starting:

Python 3.10+
ClickHouse server accessible from the host

Install and run the MCP server with the following steps:

# 1) Clone the project repository
git clone https://github.com/ThomAub/clickhouse_mcp_server.git
cd clickhouse_mcp_server

# 2) Install required packages
uv sync --all-extras

# 3) Configure ClickHouse connection details in environment variables
# or edit the server code to provide connection details

Additional sections

Configuration and usage notes follow, based on how the server is designed to run and be configured.

Available tools

list_databases

Lists available ClickHouse databases as MCP resources so your client can enumerate data sources.

list_tables

Lists all tables within a selected ClickHouse database, enabling resource discovery for specific datasets.

get_schema

Retrieves the schema for a specified ClickHouse table, including column names, types, and any constraints.

execute_query

Executes a SELECT query against a ClickHouse table and returns results to the MCP client.