ClickHouse MCP Server

How to use

You interact with the server through an MCP client. The server exposes several functional endpoints that you can call to run queries and fetch metadata. The primary capabilities you’ll use are: to run read-only SQL queries against ClickHouse, to list databases, and to list tables with optional filters and pagination. If you enable chDB, you can also exercise the embedded ClickHouse engine for local development.

Key tools implemented by the server include: run_select_query to execute read-only SQL against ClickHouse, list_databases to enumerate databases, list_tables to fetch tables with paging and optional filters, and run_chdb_select_query to query the embedded chDB engine. Each tool is designed for safe operation and clear responses to help you build reliable data workflows.

How to install

Prerequisites you need before starting: a runtime environment for the MCP server (as shown in the examples), and a reachable ClickHouse instance for the server to connect to. You can run the server locally for development or connect to a remote ClickHouse deployment.

Install and run the MCP server using the provided runtime command. The examples use a local MCP runner to start the server with Python support and the ClickHouse connector.

{
  "mcpServers": {
    "mcp_clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.10",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_PORT": "<clickhouse-port>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
      }
    }
  }
}

Configuration and environment variables

Configure the MCP server to connect to your ClickHouse deployment by setting the environment variables shown in the examples. These variables control the host, port, credentials, security, and timeouts. You may enable either the standard ClickHouse connection or the embedded chDB engine, or both, depending on your development needs.

{
  "mcpServers": {
    "mcp_clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.10",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_PORT": "<clickhouse-port>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30",
        "CHDB_ENABLED": "true",
        "CHDB_DATA_PATH": "/path/to/chdb/data"
      }
    }
  }
}

Health check and endpoints

If you expose the server over HTTP or SSE, you’ll have a health check endpoint at /health. A healthy server returns a 200 OK and the ClickHouse version; if the server cannot connect to ClickHouse, you’ll receive a 503.

curl http://localhost:8000/health
# Response: OK - Connected to ClickHouse <version>

Additional notes

For development and testing, you can run the server with different transport options to suit your tooling. The examples show starting with a local MCP runner (uv) and using the embedded Python runtime. You can also test with a direct system Python invocation if you prefer not to use the MCP runner.

run_select_query

Executes a read-only SQL query against your ClickHouse cluster using a safe readonly setting.

list_databases

Lists all databases available in your ClickHouse cluster.

list_tables

Lists tables within a database with pagination and optional filters.

run_chdb_select_query

Executes SQL queries using chDB's embedded ClickHouse engine.

health_check

Returns health status and ClickHouse version when using HTTP transport.