Clickhouse MCP Server

🚀 ClickHouse MCP Server

A Model Context Protocol (MCP) server implemented for ClickHouse. It provides a secure and structured way for AI assistants to explore and analyze databases, allowing them to list tables, read data, and execute SQL queries through a controlled interface to ensure responsible database access.

🚀 Quick Start

Configuration

You can set the following environment variables:

CLICKHOUSE_HOST=localhost    
CLICKHOUSE_PORT=8123         
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=CHANGE_TO_YOUR_PASSWORD
CLICKHOUSE_DATABASE=default

Or use command-line parameters:

• --host: Database host
• --port: Database port
• --user: Database username
• --password: Database password
• --database: Database name

Usage

Assume some data in ClickHouse

Please refer to the SQL statements in the dev_contribute.md file.

Ask questions to the AI assistant in Cline

What is the sales volume in each region? Which product is the best - selling?

CLINE

Configure the MCP server in VSCode, the Cline extension, or other MCP clients. Here is an example:

{
  "mcpServers": {
    "clickhouse": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/clickhouse_mcp_server",
        "run",
        "-m",
        "clickhouse_mcp_server.server"
      ],
      "env": {
        "CLICKHOUSE_HOST": "localhost",
        "CLICKHOUSE_PORT": "8123",
        "CLICKHOUSE_USER": "default",
        "CLICKHOUSE_PASSWORD": "CHANGE_TO_YOUR_PASSWORD",
        "CLICKHOUSE_DATABASE": "default"
      }
    }
    
  }
}

📄 License

APACHE - For detailed information, please refer to the LICENSE file.

🔧 Contribution

Please refer to dev_contribute.md for detailed information.

Prerequisites

• Python with the uv package manager
• ClickHouse installed
• Dependencies for the MCP server

🙏 Acknowledgments

The implementation of this library is inspired by the following three repositories, and their code is referenced, respecting the open-source spirit!

• GreptimeTeam/greptimedb-mcp-server
• ktanaka101/mcp-server-duckdb
• designcomputer/mysql_mcp_server)

Thank you!