MCP Timeplus

🚀 ClickHouse MCP Server

A MCP server for ClickHouse.

🚀 Quick Start

This is a MCP server designed for ClickHouse, offering seamless integration and efficient data operations.

✨ Features

• Provide MCP protocol support and integrate with ClickHouse.
• Support the execution of SQL queries and other ClickHouse operations.

💻 Usage Examples

Basic Usage

1. Execute SQL Queries

# Example: Query data from a table
SELECT * FROM table_name;

2. List All Databases

# Example: List all databases
SHOW DATABASES;

3. List All Tables

# Example: List tables in a specified database
USE database_name;
SHOW TABLES;

📦 Installation

Configuration

Add the following content to the configuration file:

{
  "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>"
      }
    }
  }
}

📚 Documentation

Development Guide

Environment Requirements

• Install Python 3.10 or a higher version.
• Install the ClickHouse database.

Quick Start (Using Docker)

# Start the ClickHouse container
docker-compose up -d

# Enter the container
docker exec -it clickhouse bash

Example Configurations

Local Development Environment

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

# Optional variables (override default values)
CLICKHOUSE_SECURE=false  # Use port 8123
CLICKHOUSE_VERIFY=false

ClickHouse Cloud Environment

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

# Optional variables (use secure default values)
# CLICKHOUSE_SECURE=true  # Use port 8443
# CLICKHOUSE_DATABASE=your_database

ClickHouse SQL Playground

CLICKHOUSE_HOST=sql-clickhouse.clickhouse.com
CLICKHOUSE_USER=demo
CLICKHOUSE_PASSWORD=
# Use HTTPS and port 8443 by default

⚠️ Important Note

• The environment variables in the configuration file can be set in the .env file or directly in the terminal.
• In a production environment, ensure that CLICKHOUSE_VERIFY is set to true to ensure data security.

By following the above steps, you can easily configure and run the ClickHouse MCP server.