ClickHouse MCP Server
An MCP server that lets AI assistants list databases and tables and run SQL queries on ClickHouse or the embedded chDB engine.
Tested on Linux
Use it
Linux x86_64
You need first
- Runtimes:
python>=3.10,<=3.15 - System packages:
C compiler (for lz4 on Python 3.15)
uv tool install 'mcp-clickhouse[chdb]' (puts mcp-clickhouse on PATH, with the chDB extra)
uv tool install 'mcp-clickhouse[chdb]'
Add it to your agent
claude mcp add mcp-clickhouse -- mcp-clickhouseJSON for Claude Desktop, Cursor and other clients
{
"mcpServers": {
"mcp-clickhouse": {
"command": "mcp-clickhouse",
"args": []
}
}
}Add mcp-clickhouse as an MCP server in your AI assistant's settings, with CHDB_ENABLED=true to use the embedded chDB engine or your ClickHouse connection details to query a cluster.
What it does
- Query data with the embedded chDB engineTested
How to use it
- Start the server with chDB on and ClickHouse off:
CHDB_ENABLED=true CLICKHOUSE_ENABLED=false mcp-clickhouse. - Connect your MCP client to the server.
- Ask the assistant to call the run_chdb_select_query tool with a SELECT query, such as
SELECT number, number*2 AS doubled FROM numbers(3).
- Start the server with chDB on and ClickHouse off:
- Run SQL queries on ClickHouseNot tested
- List databases and tablesNot tested
- Use read-only mode by defaultNot tested
How far pickfit got
Linux x86_64
- Installs
- Connects
- 1 of 4 features work
- Works offline
Good for
- run SQL queries on a ClickHouse cluster from an AI assistant
- query files and URLs with embedded chDB without ETL
- estimate query cost before running it
How pickfit tested it
Each run starts from a clean machine and follows the steps above. How pickfit verifies
Linux x86_64
An MCP client called one of its tools
- Replayed from scratch
- Works offline
- Checked on 15 Nov 2026
- Version 0.7.0
An MCP client handshake over stdio listed 1 tool, and a call to run_chdb_select_query returned a result.
Differences the test machine hit
- README: pip install mcp-clickhouse (base package); run_chdb_select_query requires the optional chdb extra
In the test: Installed with uv tool install 'mcp-clickhouse[chdb]' so the chDB tool works. Without CHDB_ENABLED=true only the ClickHouse tools are listed. - README: ClickHouse tools need a reachable ClickHouse server (CLICKHOUSE_HOST etc.)
In the test: The official ClickHouse binary from builds.clickhouse.com crashed with a segfault in this sandbox, so the box had no local server. run_query, list_databases and list_tables could not be tested.