home / mcp / clickhouse mcp server

ClickHouse MCP Server

An MCP-compatible server for interacting with ClickHouse databases, enabling database discovery, table listing, schema inspection, and SQL execution.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "headcrab-clickhouse-mcp": {
      "command": "clickhouse-mcp",
      "args": [
        "-url",
        "localhost:9000/default",
        "-user",
        "default",
        "-password",
        "yourpassword"
      ]
    }
  }
}

You can use this MCP server to interact with ClickHouse databases by exposing MCP-compatible endpoints that let you discover databases, list tables, inspect table schemas, and run SQL queries. It supports multiple transport methods and is designed to be connected to MCP clients for convenient data access and exploration.

How to use

To start using the server, run it locally and connect your MCP client to the provided endpoint. You can operate in standard stdio mode or switch to SSE for streaming over HTTP. The server can list databases, show tables in a database, reveal a table’s schema, and execute SQL queries with results returned to your client.

How to install

Prerequisites: you need Go installed on your machine to build the MCP server from source.

Step 1: Build the server

go build -o clickhouse-mcp

Step 2: Run the server in stdio mode (default transport)

./clickhouse-mcp -url localhost:9000/default -user default -password yourpassword

Step 3: Run the server with SSE transport

./clickhouse-mcp -t sse -url localhost:9000/default -user default -password yourpassword

Additional sections

Configuration options you can use when starting the server include the following flags. They control how you connect to ClickHouse and how you transport data to your MCP client.

CLI options to know about

- -t, -transport: Type of transport (stdio or sse); default is stdio.

- -test: Run in test mode to show example queries.

- -url: ClickHouse host:port and database in the form host:port/database.

- -user: ClickHouse username; default is default.

- -password: ClickHouse password.

- -db: Override the database in the URL.

- -secure: Use TLS if needed.

Note that you can also run the server via Docker or Docker Compose using the examples provided for containerized deployment.

Available tools

get_databases

Returns the list of databases available in the connected ClickHouse server.

get_tables

Retrieves the tables contained within a specified database.

get_schema

Fetches the schema definition for a specified table in a database.

query

Executes a SQL query against the connected ClickHouse database and returns the results.