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:

{
  "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": "30",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
      }
    }
  }
}

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.13",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
        "CLICKHOUSE_PORT": "8443",
        "CLICKHOUSE_USER": "demo",
        "CLICKHOUSE_PASSWORD": "",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
      }
    }
  }
}

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.

default

CLICKHOUSE_HOST=localhost
CLICKHOUSE_PORT=8123
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse

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

# Required variables
CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse

# Optional: Override defaults for local development
CLICKHOUSE_SECURE=false  # Uses port 8123 automatically
CLICKHOUSE_VERIFY=false

# Required variables
CLICKHOUSE_HOST=your-instance.clickhouse.cloud
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=your-password

# Optional: These use secure defaults
# CLICKHOUSE_SECURE=true  # Uses port 8443 automatically
# CLICKHOUSE_DATABASE=your_database

CLICKHOUSE_HOST=sql-clickhouse.clickhouse.com
CLICKHOUSE_USER=demo
CLICKHOUSE_PASSWORD=
# Uses secure defaults (HTTPS on port 8443)

.env

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.13",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_DATABASE": "<optional-database>"
      }
    }
  }
}

YouTube Overview