list_databases
List available ClickHouse databases
LABSCO SUMMARY
It turns 'what does this table look like' into one call instead of a psql session.
The table listing returns schema, comment, row count and column count together, which is usually enough for the model to write a correct query on the first attempt rather than exploring with SELECT *. The write path is a deliberate switch, and drops need a second one — without them the server answers questions and changes nothing.
What it is
ClickHouse's own MCP server: list the databases, list a database's tables with their schema and size, and run SQL. Queries execute read-only unless CLICKHOUSE_ALLOW_WRITE_ACCESS is set.
What you get
- The databases on the connected cluster, listed
- Tables in a database with schema, comment, row count and column count, filtered by LIKE or NOT LIKE, paged 50 at a time, and with column metadata droppable for a lighter response
- SQL executed read-only by default; CLICKHOUSE_ALLOW_WRITE_ACCESS=true enables DDL and DML, and CLICKHOUSE_ALLOW_DROP is a second switch for drops and truncates
- A per-query timeout, 30 seconds by default, so a runaway scan fails instead of hanging the session
- A session role activated on connect through CLICKHOUSE_ROLE, so the agent inherits exactly the grants that role carries
- An unauthenticated /health endpoint when it runs over HTTP or SSE, answering 200 only while it can actually reach ClickHouse
- Bearer-token auth on the HTTP transports, or a FastMCP identity provider for a production deployment
Requirements
Python with uv, a reachable ClickHouse instance, and CLICKHOUSE_HOST, CLICKHOUSE_USER and CLICKHOUSE_PASSWORD. The connection is HTTPS by default, which is why the port defaults to 8443 and drops to 8123 when CLICKHOUSE_SECURE is false. A Docker image is published too.
Setup effort
One command plus credentials — python3 -m pip install mcp-clickhouse, then supply credentials
USE CASES
01
Getting oriented in a cluster you did not build
List the databases, then the tables in the one that matters — the row counts alone show which tables are real.
02
Answering an analytics question in one pass
Read the schema first so the query names real columns, then run the SQL and get the rows back.
03
Letting an agent explore production safely
Leave write access off and set a session role — the tool list is the same, but nothing it runs can change data.
04
Working through a table with thousands of others around it
Filter the table list by pattern and page through it, rather than pulling every table's metadata into context.
3 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
list_tables
List available ClickHouse tables in a database, including schema, comment, row count, and column count.
Args: database: The database to list tables from like: Optional LIKE pattern to filter table names not_like: Optional NOT LIKE pattern to exclude table names page_token: Token for pagination, obtained from a previous call page_size: Number of tables to return per page (default: 50) include_detailed_columns: Whether to include detailed column metadata (default: True). When False, the columns array will be empty but create_table_query still contains all column information. This reduces payload size for large schemas.
Returns: A JSON-encoded string of an object containing:
- tables: List of table information (as dictionaries)
- next_page_token: Token for the next page, or None if no more pages
- total_tables: Total number of tables matching the filters
run_query
Execute SQL queries in ClickHouse. Queries run in read-only mode by default. Set CLICKHOUSE_ALLOW_WRITE_ACCESS=true to allow DDL and DML operations. Set CLICKHOUSE_ALLOW_DROP=true to additionally allow destructive operations (DROP, TRUNCATE).
BEFORE YOU INSTALL
What to know first
Tools you get
3 tools when we connected; the project documents 4. run_chdb_select_query needs the chdb extra: pip install 'mcp-clickhouse[chdb]'. run_query is read-only by default; CLICKHOUSE_ALLOW_WRITE_ACCESS enables writes and CLICKHOUSE_ALLOW_DROP enables DROP and TRUNCATE.
Requires
- uv on PATH
- CLICKHOUSE_PASSWORD in your environment
- CLICKHOUSE_HOST in your environment
- CLICKHOUSE_USER in your environment
Where it runs
Both documented setups run the server on your machine.
INSTALLATION
Connect your client
Server setup
TERMINAL
python3 -m pip install mcp-clickhouseMCP Clients
Claude Desktop
CLAUDE DESKTOP · JSON
{
"mcpServers": {
"mcp-clickhouse": {
"command": "uv",
"args": [
"run",
"--with",
"mcp-clickhouse",
"--python",
"3.10",
"mcp-clickhouse"
],
"env": {
"CLICKHOUSE_HOST": "<YOUR_CLICKHOUSE_HOST>",
"CLICKHOUSE_PORT": "<YOUR_CLICKHOUSE_PORT>",
"CLICKHOUSE_USER": "<YOUR_CLICKHOUSE_USER>",
"CLICKHOUSE_PASSWORD": "<YOUR_CLICKHOUSE_PASSWORD>",
"CLICKHOUSE_SECURE": "true",
"CLICKHOUSE_VERIFY": "true"
}
}
}
}Claude Desktop — demo playground
CLAUDE DESKTOP — DEMO PLAYGROUND · JSON
{
"mcpServers": {
"mcp-clickhouse": {
"command": "uv",
"args": [
"run",
"--with",
"mcp-clickhouse",
"--python",
"3.10",
"mcp-clickhouse"
],
"env": {
"CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
"CLICKHOUSE_PORT": "8443",
"CLICKHOUSE_USER": "demo",
"CLICKHOUSE_PASSWORD": "",
"CLICKHOUSE_SECURE": "true",
"CLICKHOUSE_VERIFY": "true",
"CLICKHOUSE_CONNECT_TIMEOUT": "30",
"CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
}
}
}
}
