ClickHouse/mcp-clickhouse

What it solves

This project provides a Model Context Protocol (MCP) server that allows AI assistants (like Claude Desktop) to interact directly with ClickHouse databases. It bridges the gap between LLMs and structured data stored in ClickHouse, enabling the AI to query, explore, and analyze data without requiring the user to manually export files or write every query themselves.

How it works

The server acts as an intermediary that exposes specific ClickHouse tools to an MCP-compatible client. It supports two modes of operation: connecting to a remote ClickHouse cluster or using chDB, an embedded ClickHouse engine for querying data from files or URLs without ETL processes.

Key capabilities include:

• Query Execution: Running SQL queries with support for named parameters to prevent SQL injection and handle complex types.
• Database Exploration: Listing databases and tables (with pagination and filtering) to help the AI understand the schema.
• Query Inspection: Using DESCRIBE to check result schemas and EXPLAIN ESTIMATE to predict the resource cost of a query before execution.
• Security: Implementing read-only mode by default and providing multiple authentication methods (Static Bearer tokens or OAuth/OIDC) for HTTP/SSE transports.

Who it’s for

• Data Analysts and Engineers: Who want to use AI to explore large datasets in ClickHouse.
• AI Application Developers: Who want to give their LLM agents the ability to perform real-time data retrieval from a ClickHouse database.
• DevOps Engineers: Who need a way to integrate ClickHouse data access into an MCP-based AI ecosystem.

Highlights

• Dual Engine Support: Works with both full ClickHouse clusters and the embedded chDB engine.
• Safe Exploration: Default read-only access and tools for estimating query costs to prevent expensive scans.
• ** idea-safe Parameterization**: Uses {name:Type} placeholders for secure and precise data binding.
• Enterprise-Ready Auth: Supports a wide range of OIDC providers via FastMCP for production deployments.