ClickHouse MCP Integration Package

This module facilitates interaction with ClickHouse databases via the Message-Passing Control Protocol (MCP) server architecture.

Capabilities Overview

Direct ClickHouse Operations

run_select_query
Executes arbitrary SQL queries against the remote ClickHouse cluster.
Parameter: sql (text): The Data Manipulation Language statement intended for execution.
Safety Precaution: All queries are automatically constrained with readonly = 1 to prevent unintended data modifications.
list_databases
Retrieves a catalog of all accessible schemas within the ClickHouse environment.
list_tables
Fetches the schema definitions present within a specified database.
Parameter: database (text): Identifier for the target schema.

Embedded chDB Engine Access

run_chdb_select_query
Runs SQL statements utilizing the embedded chDB engine.
Parameter: sql (text): The SQL instruction to process.
This tool allows for immediate querying of local files, remote URIs, or other integrated sources without requiring conventional Extract-Transform-Load (ETL) workflows.

Operational Status Endpoint

When deployed using HTTP or Server-Sent Events (SSE) transport layers, a diagnostics endpoint is exposed at /health. - Healthy Status: Responds with 200 OK including the connected ClickHouse software version. - Unhealthy Status: Returns 503 Service Unavailable if connectivity to the ClickHouse backend is lost.

Example Health Check: bash curl http://localhost:8000/health

Expected Output: OK - Connected to ClickHouse 24.3.1

Integration Configuration Guide

This server supports configuration for both the remote ClickHouse instance and the local chDB engine.

Locate Configuration File: Access your Claude Desktop settings file:
macOS path: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows path: %APPDATA%/Claude/claude_desktop_config.json
Insert Server Definition (Remote ClickHouse Example):

{ "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_SECURE": "true", "CLICKHOUSE_VERIFY": "true", "CLICKHOUSE_CONNECT_TIMEOUT": "30", "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30" } } } }

Adjust the environment variables to match your specific ClickHouse service credentials.

Using ClickHouse SQL Playground Configuration:

{ "mcpServers": { "mcp-clickhouse": { "command": "uv", "args": [ "run", "--with", "mcp-clickhouse", "--python", "3.10", "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" } } } }

Configuration for chDB Only (Embedded Mode):

{ "mcpServers": { "mcp-clickhouse": { "command": "uv", "args": [ "run", "--with", "mcp-clickhouse", "--python", "3.10", "mcp-clickhouse" ], "env": { "CHDB_ENABLED": "true", "CLICKHOUSE_ENABLED": "false", "CHDB_DATA_PATH": "/path/to/chdb/data" } } } }

Enabling Both Services Simultaneously:

Resolve UV Executable Path: If using the uv execution method, update the configuration to point to the absolute path of the uv binary. On macOS, this path can be discovered via which uv.
Activation: Relaunch Claude Desktop for the configuration modifications to take effect.

Alternative: Direct System Python Invocation

If you wish to bypass the uv dependency and utilize your system's Python environment, perform these setup steps:

Package Installation: Install the utility via pip: bash python3 -m pip install mcp-clickhouse

For updates: bash python3 -m pip install --upgrade mcp-clickhouse

Configuration Update (Using Python Module):

{ "mcpServers": { "mcp-clickhouse": { "command": "python3", "args": [ "-m", "mcp_clickhouse.main" ], "env": { "CLICKHOUSE_HOST": "", "CLICKHOUSE_PORT": "", "CLICKHOUSE_USER": "", "CLICKHOUSE_PASSWORD": "", "CLICKHOUSE_SECURE": "true", "CLICKHOUSE_VERIFY": "true", "CLICKHOUSE_CONNECT_TIMEOUT": "30", "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30" } } } }

Configuration Update (Using Installed Script):

{ "mcpServers": { "mcp-clickhouse": { "command": "mcp-clickhouse", "env": { "CLICKHOUSE_HOST": "", "CLICKHOUSE_PORT": "", "CLICKHOUSE_USER": "", "CLICKHOUSE_PASSWORD": "", "CLICKHOUSE_SECURE": "true", "CLICKHOUSE_VERIFY": "true", "CLICKHOUSE_CONNECT_TIMEOUT": "30", "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30" } } } }

Note: Ensure that the specified executable (python3 or mcp-clickhouse) is accessible via the system's PATH, or provide its absolute location.

Local Development Setup

Start Infrastructure: Within the test-services directory, initiate the required ClickHouse infrastructure using: docker compose up -d.
Environment Variables: Create a .env file in the repository root to store connection parameters.

Warning: The default user access noted below is strictly for local testing environments only.

bash CLICKHOUSE_HOST=localhost CLICKHOUSE_PORT=8123 CLICKHOUSE_USER=default CLICKHOUSE_PASSWORD=clickhouse

Dependency Installation: Synchronize dependencies with uv sync. If uv is missing, follow the installation instructions here. Subsequently, activate the virtual environment: source .venv/bin/activate.
Server Launch (Development Mode): Initiate the MCP server for live testing with the MCP Inspector via: fastmcp dev mcp_clickhouse/mcp_server.py.
HTTP Transport & Health Testing: Verify functionality over HTTP/SSE: bash # Default port 8000 CLICKHOUSE_MCP_SERVER_TRANSPORT=http python -m mcp_clickhouse.main

# Custom binding port CLICKHOUSE_MCP_SERVER_TRANSPORT=http CLICKHOUSE_MCP_BIND_PORT=4200 python -m mcp_clickhouse.main

# Health check verification in a separate shell: curl http://localhost:8000/health # or http://localhost:4200/health

Configuration Variables Reference

Configuration is managed via environment variables controlling connectivity and component activation.

ClickHouse Connection Parameters

Mandatory

CLICKHOUSE_HOST: Network address of the target ClickHouse service.
CLICKHOUSE_USER: Credentials for access.
CLICKHOUSE_PASSWORD: Secret key for authentication.

[!SECURITY_WARNING] Restrict the permissions granted to the MCP user account to the absolute minimum required for its operational functions. Avoid utilizing administrative or default user credentials whenever possible.

Optional Settings

CLICKHOUSE_PORT: Specifies the service port.
Default: 8443 (secure) or 8123 (insecure).
CLICKHOUSE_SECURE: Toggles SSL/TLS encryption.
Default: "true".
CLICKHOUSE_VERIFY: Controls SSL certificate validation.
Default: "true" (Disabling is discouraged in production).
CLICKHOUSE_CONNECT_TIMEOUT: Maximum time (seconds) allotted for establishing a connection.
Default: "30".
CLICKHOUSE_SEND_RECEIVE_TIMEOUT: Timeout (seconds) for query execution and data transfer.
Default: "300".
CLICKHOUSE_DATABASE: Pre-selects the initial working schema.
Default: Server default.
CLICKHOUSE_MCP_SERVER_TRANSPORT: Determines the inter-process communication mechanism.
Default: "stdio". Options: "stdio", "http", "sse".
CLICKHOUSE_MCP_BIND_HOST: Network interface for binding HTTP/SSE listeners.
Default: "127.0.0.1". Use "0.0.0.0" for all interfaces.
CLICKHOUSE_MCP_BIND_PORT: Port assignment for HTTP/SSE listeners.
Default: "8000".
CLICKHOUSE_ENABLED: Toggles the availability of ClickHouse tools.
Default: "true".

chDB Embedded Engine Parameters

CHDB_ENABLED: Activates chDB functionality.
Default: "false".
CHDB_DATA_PATH: Directory location for persistent chDB storage.
Default: ":memory:" (Ephemeral memory database).

Configuration Examples Summary

For Docker-based local testing: env CLICKHOUSE_HOST=localhost CLICKHOUSE_USER=default CLICKHOUSE_PASSWORD=clickhouse CLICKHOUSE_SECURE=false CLICKHOUSE_VERIFY=false

For ClickHouse Cloud deployments: env CLICKHOUSE_HOST=your-instance.clickhouse.cloud CLICKHOUSE_USER=default CLICKHOUSE_PASSWORD=your-password

Secure defaults (HTTPS) are applied automatically

For chDB (in-memory): env CHDB_ENABLED=true CLICKHOUSE_ENABLED=false

For HTTP transport access (e.g., for remote MCP Inspector): env CLICKHOUSE_HOST=localhost CLICKHOUSE_USER=default CLICKHOUSE_PASSWORD=clickhouse CLICKHOUSE_MCP_SERVER_TRANSPORT=http CLICKHOUSE_MCP_BIND_HOST=0.0.0.0 CLICKHOUSE_MCP_BIND_PORT=4200

When HTTP transport is active on port 4200, the service endpoints are: - MCP Interface: http://localhost:4200/mcp - Health Status: http://localhost:4200/health

Configuration can be set directly in the env block of the desktop configuration file, as shown in the initial setup examples.

Running Automated Checks

bash uv sync --all-extras --dev # Install development dependencies uv run ruff check . # Execute static analysis and linting

docker compose up -d test_services # Initialize test ClickHouse cluster uv run pytest -v tests uv run pytest -v tests/test_tool.py # Execute ClickHouse specific tests uv run pytest -v tests/test_chdb_tool.py # Execute chDB specific tests

Video Resource

Background Information (Tree-sitter Analogy)

Note: The following section is provided as supplemental context regarding parsing technologies, analogous to how this MCP tool parses commands.

WIKIPEDIA CONTEXT: Tree-sitter is recognized in computer science as a parser generator framework complemented by an incremental parsing library.

== Details == Its primary function involves transforming source code into tangible, navigable syntax representations (Concrete Syntax Trees), valuable for compilers, interpreters, code editors, and analytical tools. It is specifically engineered for interactive editing environments, featuring native support for incremental updates to the parse tree as text is modified in real-time. Furthermore, it includes an integrated S-expression query mechanism for programmatic code inspection. Text editors that officially leverage Tree-sitter include Atom, GNU Emacs, Neovim, Lapce, Zed, and Helix. Language bindings enable utilization across numerous programming environments such as Go, Haskell, Java, JavaScript (Node.js/WASM), Kotlin, Lua, OCaml, Perl, Python, Ruby, Rust, and Swift. Tree-sitter parsers have been implemented for a wide array of languages. GitHub utilizes this technology to enable in-browser symbolic navigation within code repositories. Tree-sitter is founded upon the GLR parsing algorithm, a variation of LR parsing techniques. The technology was initially created by GitHub engineers for integration into the Atom text editor, where it was first deployed in 2018.

== Related Concepts == Parser Generator Comparison

== References ==

== External Links == Official Project Site tree-sitter Repository on GitHub

mcp-data-connector-clickhouse

Author

ClickHouse

Quick Info

Actions

Tags