ClickHouse MCP

Name: ClickHouse MCP
Author: ClickHouse

by ClickHouse

Query ClickHouse databases with natural language for real-time analytics and OLAP

database Python Intermediate Self-hostable Verified

⭐ 200 stars 📅 Updated: 1mo ago

View on GitHub View package

Description

Official ClickHouse MCP server that gives LLMs direct access to ClickHouse databases for real-time analytics and OLAP queries. Connect your AI assistant to one of the fastest columnar databases in the world and explore billions of rows through natural language. Supports listing databases and tables, describing schemas, and executing read-only SQL queries — all through a secure, controlled interface. Ideal for data exploration, ad-hoc analytics, and building AI-powered dashboards that query ClickHouse in real time.

✅ Best for

Teams using ClickHouse for analytics who want AI-assisted data exploration

⏭️ Skip if

You need write access to the database or use a different DBMS

💡 Use cases

Exploring large analytical datasets through conversational queries
Running ad-hoc OLAP queries on ClickHouse without writing SQL manually
Building AI-driven dashboards that pull real-time metrics from ClickHouse
Investigating data quality issues by inspecting schemas and sample data

👍 Pros

✓ Official project maintained by the ClickHouse team
✓ Optimized for ClickHouse's columnar engine — fast queries on billions of rows
✓ Simple setup via pip install or uvx with environment variable configuration
✓ Read-only query execution ensures safe data exploration

👎 Cons

✗ Requires a running ClickHouse instance with network access
✗ Limited to read operations — no data insertion or schema modifications
✗ Complex analytical queries may produce large result sets that consume context

🔧 Exposed tools (4 tools)

Tool	Category	Description
list_databases	discovery	List all available databases in the ClickHouse instance
list_tables	discovery	List all tables in a specific database
describe_table	discovery	Get the schema and column details of a table
execute_query	query	Execute a read-only SQL query against ClickHouse

⚡ Installation

Prerequisites:

• python v3.10+
• ClickHouse instance credentials (host, user, password)
• API key required

Check Claude Code documentation to configure this MCP server.

💡 Tips & tricks

Set CLICKHOUSE_HOST, CLICKHOUSE_USER, and CLICKHOUSE_PASSWORD as environment variables. For ClickHouse Cloud, use the secure connection string provided in your cloud console. Start with list_databases and list_tables to orient the LLM before running queries.

🔄 Alternatives

MotherDuck MCP

Query and analyze data with MotherDuck serverless DuckDB and local files via SQL

Similar functionality

Tinybird MCP

Real-time analytics on Tinybird serverless ClickHouse — query, manage pipes, and publish APIs