Overview

The ClickHouse MCP Server provides a robust interface for AI models to interact with ClickHouse, a column-oriented database management system for online analytical processing (OLAP). It enables AI to perform high-performance analytical queries, manage data warehousing, and conduct real-time analytics, making it ideal for large-scale data analysis and business intelligence applications.

Created by:

Developed by ClickHouse

Key Features

⚡

High-Performance Analytics

Execute analytical queries on massive datasets with extreme speed.

📊

Data Warehousing

Efficiently store and manage large volumes of historical and real-time data.

🔍

Schema Inspection

Inspect database schemas, tables, and column details for better data understanding.

🚀

Real-time Data Processing

Process and analyze data streams in real-time for immediate insights.

Available Tools

Quick Reference

Tool	Purpose	Category
`run_select_query`	Execute SELECT queries	Read
`list_databases`	List all databases	Schema
`list_tables`	List tables in a database	Schema
`run_chdb_select_query`	Execute SQL queries using chDB	Read

Detailed Usage

run_select_query▶

Execute SQL queries on your ClickHouse cluster. All queries are run with readonly = 1 to ensure they are safe.

use_mcp_tool({
  server_name: "clickhouse",
  tool_name: "run_select_query",
  arguments: {
    sql: "SELECT * FROM my_table LIMIT 10"
  }
});

Returns the results of the SELECT query.

list_databases▶

List all databases on your ClickHouse cluster.

use_mcp_tool({
  server_name: "clickhouse",
  tool_name: "list_databases",
  arguments: {}
});

Returns a list of database names.

list_tables▶

List all tables in a specified database.

use_mcp_tool({
  server_name: "clickhouse",
  tool_name: "list_tables",
  arguments: {
    database: "default"
  }
});

Returns a list of table names within the database.

run_chdb_select_query▶

Execute SQL queries using chDB's embedded ClickHouse engine. Query data directly from various sources (files, URLs, databases) without ETL processes.

use_mcp_tool({
  server_name: "clickhouse",
  tool_name: "run_chdb_select_query",
  arguments: {
    sql: "SELECT * FROM file('data.csv')"
  }
});

Returns the results of the SELECT query from chDB.

Installation

{
  "mcpServers": {
    "clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.10",
        "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"
      }
    }
  }
}

Configuration:

Update the environment variables to point to your own ClickHouse service. Replace <clickhouse-host>, <clickhouse-port>, <clickhouse-user>, and <clickhouse-password> with your actual ClickHouse credentials.

Common Use Cases

1. Real-time Dashboards

Build interactive dashboards for real-time monitoring and analytics:

use_mcp_tool({
  server_name: "clickhouse",
  tool_name: "run_select_query",
  arguments: {
    sql: "SELECT event_time, user_id, action FROM website_events WHERE event_time >= now() - INTERVAL 1 HOUR ORDER BY event_time DESC"
  }
});

2. Log Analysis

Analyze large volumes of log data for anomaly detection and troubleshooting:

use_mcp_tool({
  server_name: "clickhouse",
  tool_name: "run_select_query",
  arguments: {
    sql: "SELECT level, COUNT(*) as count FROM application_logs WHERE log_time >= today() GROUP BY level"
  }
});

3. IoT Data Processing

Process and store high-velocity IoT sensor data for immediate insights:

use_mcp_tool({
  server_name: "clickhouse",
  tool_name: "run_select_query",
  arguments: {
    sql: "SELECT device_id, AVG(temperature) as avg_temp FROM sensor_data WHERE timestamp >= now() - INTERVAL 1 DAY GROUP BY device_id"
  }
});

Connection String Format

The ClickHouse MCP server connects to a ClickHouse instance using environment variables for host, port, user, and password. It also supports secure connections (TLS/SSL).

Host: CLICKHOUSE_HOST (e.g., localhost or sql-clickhouse.clickhouse.com)
Port: CLICKHOUSE_PORT (e.g., 8123 for HTTP, 9000 for native, 8443 for HTTPS)
User: CLICKHOUSE_USER
Password: CLICKHOUSE_PASSWORD
Secure Connection: CLICKHOUSE_SECURE (set to true for TLS/SSL)
Verify TLS/SSL: CLICKHOUSE_VERIFY (set to true to verify certificates)

ClickHouse MCP Server