ClickHouse MCP Server

@ClickHouse

About ClickHouse MCP Server

Connect ClickHouse to your AI assistants.

Config

Add this server to your MCP-compatible client using the configuration below.

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.13",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
        "CLICKHOUSE_PORT": "8443",
        "CLICKHOUSE_USER": "demo",
        "CLICKHOUSE_PASSWORD": "",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
      }
    }
  }
}

Tools

No tools detected

We auto-extract tools from the README. The maintainer can list them under a ## Tools heading to populate this section.

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.

Frequently asked questions

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.

Comments

Basic information

More Databases MCP servers

MCP Alchemy

runekaagaard

A MCP (model context protocol) server that gives the LLM access to and knowledge about relational databases like SQLite, Postgresql, MySQL & MariaDB, Oracle, and MS-SQL.

412

Redis

modelcontextprotocol

Model Context Protocol Servers

88.2K

nuzur

nuzur is a model-first database platform for MySQL and PostgreSQL. The MCP server lets any AI assistant or agent (Claude, Cursor, Gemini, or anything else that speaks MCP) design your schema, query your data, generate mi

Multi Database MCP Server

FreePeak

A powerful multi-database server implementing the Model Context Protocol (MCP) to provide AI assistants with structured access to databases.

397

Database Gateway

centralmind

Universal MCP-Server for your Databases optimized for LLMs and AI-Agents.

531