ClickHouse MCP Server

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

1. Open the Claude Desktop configuration file located at: - On macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` - On Windows: `%APPDATA%/Claude/claude_desktop_config.json`

2. Add the following:

1. Locate the command entry for `uv` and replace it with the absolute path to the `uv` executable. This ensures that the correct version of `uv` is used when starting the server. On a mac, you can find this path using `which uv`.

2. Restart Claude Desktop to apply the changes.

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.

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. For easy testing, you can run `mcp dev mcp_clickhouse/mcp_server.py` to start the MCP server.

Environment Variables

Required Variables

• `CLICKHOUSE_HOST`: The hostname of your ClickHouse server

• `CLICKHOUSE_USER`: The username for authentication

• `CLICKHOUSE_PASSWORD`: The password for authentication

Optional Variables

• `CLICKHOUSE_PORT`: The port number of your ClickHouse server - Default: `8443` if HTTPS is enabled, `8123` if disabled - Usually doesn't need to be set unless using a non-standard port

• `CLICKHOUSE_SECURE`: Enable/disable HTTPS connection - Default: `"true"` - Set to `"false"` for non-secure connections

• `CLICKHOUSE_VERIFY`: Enable/disable SSL certificate verification - Default: `"true"` - Set to `"false"` to disable certificate verification (not recommended for production)

• `CLICKHOUSE_CONNECT_TIMEOUT`: Connection timeout in seconds - Default: `"30"` - Increase this value if you experience connection timeouts

• `CLICKHOUSE_SEND_RECEIVE_TIMEOUT`: Send/receive timeout in seconds - Default: `"300"` - Increase this value for long-running queries

• `CLICKHOUSE_DATABASE`: Default database to use - Default: None (uses server default) - Set this to automatically connect to a specific database

Example Configurations

YouTube Overview