home / mcp / clickhouse mcp server

ClickHouse MCP Server

Provides read-only SQL querying, database enumeration, and table listing for ClickHouse via MCP.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "cgrdavies-mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.13",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_PORT": "<clickhouse-port>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_CONNECT_TIMEOUT": "1800",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "1800"
      }
    }
  }
}

You can run a ClickHouse MCP Server to query and explore your ClickHouse cluster from any MCP-enabled client. This server exposes endpoints to run safe, read-only SQL queries, list databases, and list tables, making it easy to integrate ClickHouse data into your MCP workflow and dashboards.

How to use

With an MCP client, you connect to the ClickHouse MCP Server to perform three core actions: execute read-only SQL queries, list all databases, and list all tables within a database. The server ensures safety by running all SQL queries with readonly = 1. Use the available tools to retrieve schema information and run queries against your ClickHouse cluster without modifying data.

How to install

Prerequisites you need on your machine include an MCP-enabled environment and the MCP server runtime configuration ready to start. You will configure an MCP server entry in your Claude Desktop setup and then start the server using the provided runtime command.

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.13",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_PORT": "<clickhouse-port>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "1800",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "1800"
      }
    }
  }
}

Environment and startup notes

Update the environment variables to point to your own ClickHouse service or use the ClickHouse SQL Playground configuration to try things out. Remember to replace placeholders with your actual host, port, user, and password values.

To apply changes, locate the runtime entry for the MCP command (uv) and ensure it uses the absolute path to the uv executable on your system. After updating, restart Claude Desktop to apply the changes.

Development and testing notes

If you want to run a local development ClickHouse cluster for testing, you can start the test services with Docker in the test_services directory.

Create a local environment file with the ClickHouse connection details and activate your Python virtual environment before installing dependencies and starting the MCP server in development mode.

For quick testing, you can run the MCP server directly in development mode using the provided dev command.

Examples and quickStart

Example use cases you can perform after your server is up include: hall databases list, retrieve all tables in a database, and run a safe SQL query against your ClickHouse cluster. These actions help you validate connectivity and schema structure before integrating with dashboards or applications.

Available tools

run_select_query

Execute a SQL query against your ClickHouse cluster with safe, read-only settings (readonly=1).

list_databases

List all databases available on your ClickHouse cluster.

list_tables

List all tables within a specified database.