ClickHouse MCP Server
# ClickHouse MCP Server
# Migrated to https://github.com/ClickHouse/mcp-clickhouse
An MCP server for ClickHouse.
## Features
### Tools
* `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.
## Configuration
> **Note**: This is a temporary configuration process that will be significantly improved once the package is published.
1. Run `uv sync` to install the dependencies. To install `uv` follow the instructions [here](https://docs.astral.sh/uv/). Then do `source .venv/bin/activate`.
2. 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>
```
3. Run `fastmcp install mcp_clickhouse/mcp_server.py -f .env.production` to install the server.
4. Restart Claude Desktop.
## Development
1. In `test-services` directory run `docker compose up -d` to start the ClickHouse cluster.
2. 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=clickhouse
```
3. Run `uv sync` to install the dependencies. To install `uv` follow the instructions [here](https://docs.astral.sh/uv/). Then do `source .venv/bin/activate`.
4. For easy testing, you can run `fastmcp dev mcp_clickhouse/mcp_server.py` to start the MCP server.
TDQS
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.