home / mcp / clickhouse mcp server

Clickhouse MCP Server

An MCP server implementation that enables Claude AI to interact with Clickhouse databases.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "burakdirin-clickhouse-mcp-server": {
      "command": "uv",
      "args": [
        "run",
        "clickhouse-mcp-server"
      ],
      "env": {
        "CLICKHOUSE_HOST": "localhost",
        "CLICKHOUSE_USER": "root",
        "CLICKHOUSE_DATABASE": "[optional]",
        "CLICKHOUSE_PASSWORD": "password",
        "CLICKHOUSE_READONLY": "true"
      }
    }
  }
}

You run a Clickhouse MCP Server to connect to a Clickhouse database and run SQL queries through a lightweight MCP interface. This lets you manage connections and execute queries from MCP clients in a consistent, scriptable way.

How to use

You will connect your MCP-enabled client to the Clickhouse MCP Server and then use the provided tools to work with Clickhouse data. The two core capabilities are connecting to a specific database and executing queries. When you connect, you receive a confirmation that the connection is established. When you execute queries, you receive results in JSON format. You can send multiple queries separated by semicolons in a single request. Use this to build automation that reads, writes, and analyzes data across your Clickhouse databases.

How to install

Prerequisites you need before installing are Python and a command-line tool to install packages. You also need a working Clickhouse server you can reach from the MCP server.

Install the MCP server package using Python’s package manager or the UV tool you use to run MCP servers.

Option 1: Install with uv (recommended for development and MCP workflows) - run this command in your terminal.

uv pip install clickhouse-mcp-server

Option 2: Install with pip directly.

pip install clickhouse-mcp-server

Additional configuration and start tips

Configure the environment so the MCP server can reach your Clickhouse instance. The following environment variables control the connection details and access mode.

Required and optional environment variables are described here so you can set them in your deployment environment.

Usage configuration examples

If you want to run the server locally with a standard MCP runner, you can use one of the pre-defined commands described in the setup examples. A typical development run uses UV to locate and start the server binary with the appropriate environment variables.

Troubleshooting and debugging tips

Debugging MCP servers that run over stdio can be challenging. If you need hands-on debugging, consider using an MCP Inspector to visualize the interaction between your client and the server. You can launch the Inspector to monitor the MCP run and view the debugging URL in your browser.

Available tools

connect_database

Connects to a specific Clickhouse database. Requires the database parameter and returns a confirmation message upon successful connection.

execute_query

Executes Clickhouse SQL queries. Requires the query parameter and returns results in JSON format. Can handle multiple queries separated by semicolons.