clickhouse_mcp_server

This MCP server provides a guided interface for interacting with a ClickHouse database through a controlled Model Context Protocol (MCP) channel. It enables AI assistants to list available tables, inspect table schemas, read data from tables, and execute SQL queries against ClickHouse while honoring access boundaries defined by the MCP framework. The server is configured to connect to a ClickHouse HTTP interface and uses environment variables to manage the connection details, so you can securely supply credentials and target database at runtime. When integrated with an MCP client like VSCode Cline or other MCP-enabled tools, you can issue natural-language prompts (e.g., list all tables, show top rows from a table, or run a specific SQL query) and receive structured results that flow back into the assistant’s reasoning workflow.

Usage typically involves configuring the MCP client to point at the local uv-managed server (as shown in the CLINE example in the repository). The client can then ask questions such as: what are the tables in the default schema, what is the sales volume by region, or render data previews from a given table. The server handles the SQL translation and safety checks behind the scenes, providing a predictable, auditable surface for database access while keeping direct database exposure limited to the MCP runtime.

Prerequisites: • Python with the uv package manager installed • A running ClickHouse instance (HTTP interface on port 8123 by default) • MCP server dependencies as described in the repository

Install steps:

1. Install Python (3.8+ recommended) and ensure it is in your PATH.

2. Install the uv package manager (choose one of these options):

# Option A: install uv via pipx (recommended for isolation)
pipx install uv

# Option B: install uv via pip (system-wide)
pip install uv

3. Clone or download the MCP server code for ClickHouse (the repository this README belongs to).

git clone https://github.com/your-org/dubin555-clickhouse_mcp_server.git
cd dubin555-clickhouse_mcp_server

4. Install any additional Python dependencies required by the MCP server (if a requirements file exists):

# Example if a requirements.txt exists
python -m pip install -r requirements.txt

5. Ensure ClickHouse is accessible with the credentials you plan to use. Set environment variables as needed (see mcp_config example). You can run the server using the MCP launcher (uv) with the configuration shown in the CLINE example:

uv --directory /path/to/clickhouse_mcp_server run -m clickhouse_mcp_server.server

6. Verify the server starts and is reachable by your MCP client. If you customize host/port settings, update the environment variables accordingly in the launcher configuration.

Tips and notes:

• Ensure ClickHouse HTTP interface is enabled and reachable from the MCP server host. The default port is 8123.
• Set CLICKHOUSE_PASSWORD to a strong password and avoid exposing it in logs or shared configurations.
• If you run multiple MCP servers, keep unique environment credential values per server instance.
• The CLINE example shows how to embed environment variables in your MCP client configuration; adapt the path and module name to your project structure.
• If you encounter connection errors, verify network reachability, firewalls, and that ClickHouse authentication is configured to match the provided user/password.
• For production usage, consider adding TLS/SSL and network security hardening around the MCP server interface.
• The MCP surface is intended for SQL discovery, previews, and bounded query execution; avoid sending highly privileged operations through the MCP path unless explicitly required and audited.