The ClickHouse MCP Server allows interaction with a ClickHouse cluster to execute SQL queries and manage database objects.
Execute SQL Queries: Run run_select_query to execute read-only SQL queries on the ClickHouse cluster.
List Databases: Use list_databases to fetch all databases in the cluster.
List Tables: Use list_tables to retrieve tables within a specific database, with optional filtering.
Allows querying and interacting with ClickHouse databases, providing tools for executing SQL select queries, listing databases, and viewing tables within a database.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@ClickHouse MCP Server show me the top 10 customers by total sales"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server for ClickHouse.
run_select_query
Execute SQL queries on your ClickHouse cluster.
Input: sql (string): The SQL query to execute.
All ClickHouse queries are run with readonly = 1 to ensure they are safe.
list_databases
List all databases on your ClickHouse cluster.
list_tables
List all tables in a database.
Input: database (string): The name of the database.
Related MCP server: Altinity MCP
Note: This is a temporary configuration process that will be significantly improved once the package is published.
Run uv sync to install the dependencies. To install uv follow the instructions here. Then do source .venv/bin/activate.
Setup the .env.production file with the ClickHouse credentials.
CLICKHOUSE_HOST=<CLICKHOUSE_HOST>
CLICKHOUSE_PORT=<CLICKHOUSE_PORT>
CLICKHOUSE_USER=<CLICKHOUSE_USER>
CLICKHOUSE_PASSWORD=<CLICKHOUSE_PASSWORD>Run fastmcp install mcp_clickhouse/mcp_server.py -f .env.production to install the server.
Restart Claude Desktop.
In test-services directory run docker compose up -d to start the ClickHouse cluster.
Add the following variables to a .env file in the root of the repository.
CLICKHOUSE_HOST=localhost
CLICKHOUSE_PORT=8123
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouseRun uv sync to install the dependencies. To install uv follow the instructions here. Then do source .venv/bin/activate.
For easy testing, you can run fastmcp dev mcp_clickhouse/mcp_server.py to start the MCP server.
Inputs: no named parameters.
Inputs: database (required), like.
Inputs: query (required).
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 3 tools
Each tool has a clearly distinct purpose: list_databases retrieves database names, list_tables retrieves table names within a database, and run_select_query executes SQL queries. There is no overlap or ambiguity between these operations.
All tools follow a consistent verb_noun pattern with snake_case naming: list_databases, list_tables, run_select_query. The naming is predictable and readable throughout the set.
With only 3 tools, the set feels thin for a database server like ClickHouse, lacking operations for data manipulation (e.g., insert, update, delete), schema management (e.g., create_table), or advanced query features. However, it covers basic listing and querying.
The tool surface is significantly incomplete for a database server. It provides read-only operations (list and select) but lacks essential CRUD functionality (create, update, delete), schema modifications, or administrative tasks, which will limit agent capabilities in managing ClickHouse effectively.
MCP server for querying and analyzing data from ad platforms, analytics tools, and spreadsheets
