Happy slice of mcp pizzaMCP.pizza

mcp-clickhouse

MCP.Pizza Chef: ClickHouse

Point it at a cluster and you can ask a question in plain English, then watch it list the databases, browse the tables, and run the query that answers you. Reading is the default and writing stays switched off unless you deliberately turn it on. It also bundles chDB, a small built-in engine that reads files and links directly without loading them anywhere first. You supply the address, username, and password, and ClickHouse maintains the project themselves.

Data

Use This MCP server To

Ask which tables hold our order data Get last month's signup numbers without writing a query Explore a new database before I know what is in it Chart daily active users from our events table Check a number in production before a meeting

README

ClickHouse MCP Server

PyPI - Version

An MCP server for ClickHouse.

mcp-clickhouse MCP server

Features

ClickHouse Tools

  • run_query

    • Execute SQL queries on your ClickHouse cluster.
    • Input: query (string): The SQL query to execute.
    • Queries run in read-only mode by default (CLICKHOUSE_ALLOW_WRITE_ACCESS=false), but writes can be enabled explicitly if needed.

  • list_databases

    • List all databases on your ClickHouse cluster.

  • list_tables

    • List tables in a database with pagination.
    • Required input: database (string).
    • Optional inputs:
      • like / not_like (string): Apply LIKE or NOT LIKE filters to table names.
      • page_token (string): Token returned by a previous call for fetching the next page.
      • page_size (int, default 50): Number of tables returned per page.
      • include_detailed_columns (bool, default true): When false, omits column metadata for lighter responses while keeping the full create_table_query.
    • Response shape:
      • tables: Array of table objects for the current page.
      • next_page_token: Pass this value back to fetch the next page, or null when there are no more tables.
      • total_tables: Total count of tables that match the supplied filters.

chDB Tools

  • run_chdb_select_query
    • Execute SQL queries using chDB's embedded ClickHouse engine.
    • Input: query (string): The SQL query to execute.
    • Query data directly from various sources (files, URLs, databases) without ETL processes.
    • Requires the optional chdb extra: pip install 'mcp-clickhouse[chdb]'

Health Check Endpoint

When running with HTTP or SSE transport, a health check endpoint is available at /health. This endpoint:

  • Returns 200 OK (body: OK) if the server is healthy and can connect to ClickHouse
  • Returns 503 Service Unavailable with a generic error message if the server cannot connect to ClickHouse

mcp-clickhouse FAQ

Which apps does this work in?
The instructions cover Claude Desktop, and it connects to any app that supports MCP servers.
Do I need a password or key?
Yes. You provide the address of your ClickHouse cluster plus a username and password for it to use.
Can I use this to answer a data question without writing a query myself?
Yes. You ask in plain English and it works out and runs the query for you.
Can it change or delete my data?
Not by default. It runs in read-only mode unless you explicitly switch writing on.
How hard is the setup?
You paste a block into your app's settings and fill in your cluster details, so it is mostly copying and pasting.
Do I need a ClickHouse cluster already?
For the main tools, yes. There is also a small built-in engine that can read files and links on their own.
Is it safe to run over a network?
If you run it over the web rather than locally, it refuses to start without a login token or a sign-in provider configured.