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.

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

1. Clone the repository
2. Install requirements:

   pip install -r requirements.txt

3. Install in development mode:

   pip install -e .

Run unit tests for the improved chunking implementation:

python -m unittest tests/test_chunk_md_improved.py

python tools/chunk_md.py --save

python analyze_index_with_histogram.py

See the Tools README for more details.