ClickHouse MCP Server is a database integration that connects AI assistants to ClickHouse analytics clusters and chDB embedded engines, enabling SQL query execution and schema exploration directly from the conversation. Key features of ClickHouse MCP Server: - Execute SQL queries on ClickHouse clusters with configurable read-only or write access. - List databases and browse tables with pagination, filtering by name patterns, and optional column metadata. - Query data via chDB's embedded ClickHouse engine without a server, supporting direct reads from files, URLs, and databases without ETL. - Built-in health check endpoint for monitoring ClickHouse connectivity. - Authentication support for HTTP/SSE transports to secure connections.

ClickHouse MCP Server

[](https://pypi.org/project/mcp-clickhouse)

An MCP server for ClickHouse.

Features

ClickHouse Tools

chDB Tools

Health Check Endpoint

When running with HTTP or SSE transport, a health check endpoint is available at /health. This endpoint:

Example:

curl http://localhost:8000/health
Response: OK - Connected to ClickHouse 24.3.1

Security

Authentication for HTTP/SSE Transports

When using HTTP or SSE transport, authentication is required by default. The stdio transport (default) does not require authentication as it only communicates via standard input/output.

#### Setting Up Authentication

1. Generate a secure token (can be any random string):

   # Using uuidgen (macOS/Linux)
   uuidgen
   # Using openssl
   openssl rand -hex 32
   

2. Configure the server with the token:

   export CLICKHOUSE_MCP_AUTH_TOKEN="your-generated-token"
   

3. Configure your MCP client to include the token in requests:

For Claude Desktop with HTTP/SSE transport:

   {
     "mcpServers": {
       "mcp-clickhouse": {
         "url": "http://127.0.0.1:8000",
         "headers": {
           "Authorization": "Bearer your-generated-token"
         }
       }
     }
   }
   

For command-line tools:

   curl -H "Authorization: Bearer your-generated-token" http://localhost:8000/health
   

#### Development Mode (Disabling Authentication)

For local development and testing only, you can disable authentication by setting:

export CLICKHOUSE_MCP_AUTH_DISABLED=true

WARNING: Only use this for local development. Do not disable authentication when the server is exposed to any network.

Configuration

This MCP server supports both ClickHouse and chDB. You can enable either or both depending on your needs.

1. Open the Claude Desktop configuration file located at: * On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json * On Windows: %APPDATA%/Claude/claude_desktop_config.json

2. Add the following:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.10",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "",
        "CLICKHOUSE_PORT": "",
        "CLICKHOUSE_USER": "",
        "CLICKHOUSE_PASSWORD": "",
        "CLICKHOUSE_ROLE": "",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
      }
    }
  }
}

Update the environment variables to point to your own ClickHouse service.

Or, if you'd like to try it out with the ClickHouse SQL Playground, you can use the following config:

```json { "mcpServers": { "mcp-clickhouse": { "command": "uv", "args": [ "run", "--with", "mcp-clickhouse", "--python", "3.10", "mcp-clickhouse