connect_databaseLABSCO SUMMARY
Two tools, and the important one is the read-only flag.
execute_query runs whatever SQL you hand it, so the boundary is the ClickHouse user in your config plus CLICKHOUSE_READONLY, which is off by default. Switching database mid-session is a tool call rather than a restart.
What it is
A ClickHouse server with two tools: connect to a database, and execute queries against it.
What you get
- A named database connected to on demand, with a confirmation when it succeeds (connect_database)
- SQL executed and results returned as JSON (execute_query)
- Several statements in one call when separated by semicolons
- Connection settings from the environment — host, user and password, plus a default database if you want one
- A read-only mode through CLICKHOUSE_READONLY, off unless you turn it on
Requirements
A reachable ClickHouse server, and the package installed with uv pip install clickhouse-mcp-server or pip. Host defaults to localhost and user to root.
Setup effort
One command — uv pip install clickhouse-mcp-server
USE CASES
01
Answering a question from event data
Connect to the database that holds it, then run the query and read the JSON back.
02
Working across more than one database in a session
Switch with a connect call instead of editing config and restarting the client.
03
Letting an agent explore data without letting it change any
Turn CLICKHOUSE_READONLY on so query execution cannot write.
04
Running a short sequence of statements in one go
Separate them with semicolons and send them as a single call.
2 tools
Listed in project docs. Your client may show a different list.
execute_queryBEFORE YOU INSTALL
What to know first
Tools you get
2 tools named in the project's documentation.
Requires
- uv on PATH (the client starts the server with uvx)
- A ClickHouse server you can reach, with a username and password for it
Where it runs
The documented client runs the server on your machine.
INSTALLATION
Connect your client
Server setup
TERMINAL
uv pip install clickhouse-mcp-serverMCP Clients
Claude Desktop
CLAUDE DESKTOP · JSON
{
"mcpServers": {
"clickhouse-mcp-server": {
"command": "uvx",
"args": [
"clickhouse-mcp-server"
],
"env": {
"CLICKHOUSE_HOST": "localhost",
"CLICKHOUSE_USER": "root",
"CLICKHOUSE_PASSWORD": "password",
"CLICKHOUSE_READONLY": "true"
}
}
}
}Set CLICKHOUSE_HOST, CLICKHOUSE_USER and CLICKHOUSE_PASSWORD to your own ClickHouse server (the project defaults are localhost, root and an empty password). CLICKHOUSE_DATABASE is optional: add "CLICKHOUSE_DATABASE": "your_database" to env to start in that database.
