Neura Market
ClickHouse/mcp-clickhouse logo

ClickHouse/mcp-clickhouse

Free

ClickHouse 官方集成，连接 ClickHouse 数据库进行查询和模式检查。

FreeFree tier
Inputs: text
Type
Open Source
Company
ClickHouse
Visit Website GitHub (40 stars)

About ClickHouse/mcp-clickhouse

ClickHouse MCP Server is an open-source MCP (Model Context Protocol) integration that connects ClickHouse databases to AI assistants. It exposes tools such as run_query (execute SQL in read-only mode by default, with optional write access), list_databases, list_tables (with pagination, LIKE/NOT LIKE filters, and column detail control), and run_chdb_select_query (using the embedded chDB engine for querying files, URLs, and databases without ETL). The server supports HTTP/SSE transports with authentication modes including static bearer tokens, OAuth/OIDC, or disabled for development, and provides a minimal /health endpoint for orchestrator probes. It is built with FastMCP and the ClickHouse Python driver, and is licensed under the MIT License.

Key Features

run_query tool: Execute SQL queries on ClickHouse clusters (read-only by default, writes can be enabled)
list_databases tool: List all databases on the ClickHouse cluster
list_tables tool: List tables in a database with pagination, LIKE/NOT LIKE filters, and optional column metadata
run_chdb_select_query tool: Execute SQL queries using chDB's embedded ClickHouse engine for querying data from files, URLs, and databases without ETL
Health check endpoint: /health returns HTTP 200 with 'OK' body or 503 when ClickHouse is unreachable (unauthenticated for orchestrator probes)
Authentication modes for HTTP/SSE transports: static bearer token, OAuth/OIDC integration, or disabled for local development
Open source under MIT License, built with FastMCP

Pros & Cons

Pros
  • Read-only default mode provides safety against accidental data modification
  • Supports pagination and filtering for large databases, reducing response payload
  • Optional chDB integration allows querying files and URLs directly without ETL
  • Health check endpoint unauthenticated for easy integration with Kubernetes and load balancers
  • Multiple authentication options (static token, OAuth/OIDC) for various deployment environments
  • Open source with permissive MIT license
Cons
  • Authentication configuration required for HTTP/SSE transports, which adds setup complexity
  • Write access must be explicitly enabled and is disabled by default, limiting update operations
  • Only supports ClickHouse databases; not a general-purpose database connector
  • Requires a running ClickHouse server or chDB dependency for full functionality

Best For

Enable AI assistants to query and analyze ClickHouse data in real timeAutomate database schema exploration and inspection from conversational interfacesPerform read-only analytics on ClickHouse clusters through natural language interfacesIntegrate ClickHouse into AI workflows for reporting and data retrievalLeverage chDB for embedded querying across diverse data sources without ETL

FAQ

How do I enable write access for SQL queries?
Write access is disabled by default via the environment variable CLICKHOUSE_ALLOW_WRITE_ACCESS=false. To enable writes, set CLICKHOUSE_ALLOW_WRITE_ACCESS=true.
What authentication methods are supported for HTTP/SSE transport?
Three modes are supported: static bearer token via CLICKHOUSE_MCP_AUTH_TOKEN, OAuth/OIDC via FastMCP (configurable with provider-specific variables), and disabling authentication for local development with CLICKHOUSE_MCP_AUTH_DISABLED=true.
What is the chDB extra and how do I install it?
The chDB extra allows executing SQL queries using chDB's embedded ClickHouse engine, enabling queries on files, URLs, and databases without ETL. Install it with: pip install 'mcp-clickhouse[chdb]'.
Is the health check endpoint authenticated?
No, the /health endpoint is intentionally unauthenticated so that orchestrator probes like Kubernetes liveness/readiness and load balancers can reach it without credentials. It returns a minimal response to avoid leaking backend details.