What is Clickhouse Mcp

ClickHouse MCP is a server that implements the Model Context Protocol (MCP) for ClickHouse, providing tools to read the ClickHouse database schema, explain queries, and perform semantic searches over ClickHouse documentation.

Use cases

Use cases for ClickHouse MCP include generating documentation for ClickHouse databases, assisting developers in understanding complex queries, and enabling advanced search capabilities over database documentation.

How to use

To use ClickHouse MCP, create a virtual environment, install the package from GitHub using pip, add the MCP server to your Claude code, set up required environment variables, and run your Claude code as usual.

Key features

Key features of ClickHouse MCP include the ability to read the database schema, explain SQL queries, perform semantic searches, and integrate seamlessly with Claude for enhanced data interaction.

Where to use

ClickHouse MCP can be used in data analytics, business intelligence, and any application that requires efficient querying and semantic understanding of data stored in ClickHouse databases.

ClickHouse MCP

This project provides MCP server for ClickHouse, including MCP tools to read the
ClickHouse database schema, explain queries, and perform semantic search over the ClickHouse documentation.

Usage

Installation

0. Create a virtual environment (recommended)

python -m venv venv
source venv/bin/activate

1. Install this package directly from GitHub using pip:

pip install -e git+https://github.com/izaitsevfb/clickhouse-mcp.git#egg=clickhouse_mcp

(Just FYI: once installed, the MCP server could be run as: python -m clickhouse_mcp)

2. Add this MCP server to claude code:

claude mcp add-json clickhouse '{ "type": "stdio", "command": "python", "args": [ "-m", "clickhouse_mcp" ], "env": {} }'

Note: by default mcp config applies only to running in the current directory. If you want to use is globally, add
--scope user the command above (e.g. claude mcp add-json --scope user clickhouse ...).

3. Setup environment variables

Add .env file in the directory where you’re running claude code or export required environment variables
for the session.

See .env.example for the list of required variables related to the ClickHouse database.

AWS credentials must also be set: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN
for semantic search to work.

4. Run claude code as usual:

claude

Development

Development Installation

1. Clone the repository
2. Install requirements:

   pip install -r requirements.txt
   

3. Install in development mode:

   pip install -e .
   

Testing

Run unit tests for the improved chunking implementation:

python -m unittest tests/test_chunk_md_improved.py

Tools

Running Chunking

python tools/chunk_md.py --save

Analyzing Chunk Size Distribution (after chunking is done)

python analyze_index_with_histogram.py

See the Tools README for more details.