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