Overview
What is ClickHouse MCP Server?
An MCP server that provides tools to interact with a ClickHouse cluster, including executing SQL queries (read‑only by default), listing databases, and listing tables with pagination and filtering. Also supports chDB, an embedded ClickHouse engine, for querying data directly from files, URLs, or databases without ETL. Designed for users of MCP clients like Claude Desktop who want to explore and manage ClickHouse data through natural language or programmatic interfaces.
How to use ClickHouse MCP Server?
Install via pip install mcp-clickhouse or use uv run --with mcp-clickhouse. Configure environment variables such as CLICKHOUSE_HOST, CLICKHOUSE_PORT, CLICKHOUSE_USER, and CLICKHOUSE_PASSWORD to point to your ClickHouse instance. Optionally enable chDB by installing mcp-clickhouse[chdb] and setting CHDB_ENABLED=true. Then set the command in your MCP client configuration (e.g., Claude Desktop) to either uv run ... mcp-clickhouse or python3 -m mcp_clickhouse.main. By default queries are read-only; set CLICKHOUSE_ALLOW_WRITE_ACCESS=true to allow writes, and CLICKHOUSE_ALLOW_DROP=true to allow destructive operations.
Key features of ClickHouse MCP Server
- Execute SQL queries on ClickHouse (read‑only by default)
- List all databases in your ClickHouse cluster
- List tables with pagination, filtering (
LIKE/NOT LIKE) - Support for chDB embedded ClickHouse engine
- Health check endpoint for HTTP/SSE transports
- Authentication via static bearer token or OAuth/OIDC
Use cases of ClickHouse MCP Server
- Explore and query ClickHouse databases from AI assistants
- List databases and tables with pagination for large clusters
- Run analytical SQL queries without risking accidental writes
- Query data from files, URLs, or databases using chDB without ETL
- Integrate ClickHouse with MCP‑compatible clients like Claude Desktop
FAQ from ClickHouse MCP Server
Does ClickHouse MCP Server allow write queries by default?
No. By default queries are read‑only (CLICKHOUSE_ALLOW_WRITE_ACCESS=false). To enable INSERT, UPDATE, CREATE, etc., set CLICKHOUSE_ALLOW_WRITE_ACCESS=true. Destructive operations (DROP, TRUNCATE) additionally require CLICKHOUSE_ALLOW_DROP=true.
What authentication options are available for HTTP/SSE transports?
Three modes: static bearer token (CLICKHOUSE_MCP_AUTH_TOKEN); OAuth/OIDC via FastMCP (e.g., Azure Entra, Google, GitHub); or disable auth locally (CLICKHOUSE_MCP_AUTH_DISABLED=true). The stdio transport (default) does not require authentication.
How does the health check endpoint work?
When using HTTP or SSE transport, the /health endpoint returns 200 OK if the server can connect to ClickHouse, or 503 otherwise. It is intentionally unauthenticated for orchestrator probes and returns a minimal body to avoid leaking version information.
Does ClickHouse MCP Server support chDB?
Yes, optionally. Install mcp-clickhouse[chdb] and set CHDB_ENABLED=true to enable the run_chdb_select_query tool, which runs queries on the embedded chDB engine without needing a remote ClickHouse server.
What environment variables are required to connect to ClickHouse?
CLICKHOUSE_HOST, CLICKHOUSE_PORT, CLICKHOUSE_USER, and CLICKHOUSE_PASSWORD are required. Optional variables include CLICKHOUSE_ROLE, CLICKHOUSE_SECURE, CLICKHOUSE_VERIFY, and timeout settings.
