ClickHouse MCP Server

Features

Tools

• run_select_query

• list_databases

• list_tables

Configuration

1. Open the Claude Desktop configuration file located at:

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. 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

[!CAUTION]It is important to treat your MCP database user as you would any external client connecting to your database, granting only the minimum necessary privileges required for its operation. The use of default or administrative users should be strictly avoided at all times.

Optional Variables

• CLICKHOUSE_PORT: The port number of your ClickHouse server

• CLICKHOUSE_SECURE: Enable/disable HTTPS connection

• CLICKHOUSE_VERIFY: Enable/disable SSL certificate verification

• CLICKHOUSE_CONNECT_TIMEOUT: Connection timeout in seconds

• CLICKHOUSE_SEND_RECEIVE_TIMEOUT: Send/receive timeout in seconds

• CLICKHOUSE_DATABASE: Default database to use

Example Configurations

YouTube Overview

ClickHouse MCP Server

Features

Tools

• run_select_query

• list_databases

• list_tables

Configuration

1. Open the Claude Desktop configuration file located at:

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. 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

[!CAUTION]It is important to treat your MCP database user as you would any external client connecting to your database, granting only the minimum necessary privileges required for its operation. The use of default or administrative users should be strictly avoided at all times.

Optional Variables

• CLICKHOUSE_PORT: The port number of your ClickHouse server

• CLICKHOUSE_SECURE: Enable/disable HTTPS connection

• CLICKHOUSE_VERIFY: Enable/disable SSL certificate verification

• CLICKHOUSE_CONNECT_TIMEOUT: Connection timeout in seconds

• CLICKHOUSE_SEND_RECEIVE_TIMEOUT: Send/receive timeout in seconds

• CLICKHOUSE_DATABASE: Default database to use

Example Configurations

YouTube Overview