ClickHouse MCP Server Setup Guide

Configuration

1. Locate the Configuration File:

   • On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • On Windows: %APPDATA%/Claude/claude_desktop_config.json

2. Add the MCP Server Configuration:

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

3. Update Environment Variables:

   • Replace placeholders with your ClickHouse service details.

4. Optional Configuration for ClickHouse SQL Playground:

   {
     "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"
     }
     }
     }
    }
    

5. Locate the uv Command:

   • Replace the command entry with the absolute path to the uv executable.
   • On macOS, find this path using which uv.

6. Restart Claude Desktop:

   • Apply the configuration changes by restarting Claude Desktop.

Development

1. Start ClickHouse Cluster:

   • Run the following command in the test-services directory:

     docker compose up -d
      

2. Create a .env File:

   • Add the following variables to a .env file in the root of the repository:

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

3. Install Dependencies:

   • Run uv sync to install dependencies.
   • Follow instructions to install uv.
   • Activate the virtual environment:

     source .venv/bin/activate
      

4. Start MCP Server for Testing:

   • Run the following command:

     mcp dev mcp_clickhouse/mcp_server.py
      

Environment Variables

• Required:

  • CLICKHOUSE_HOST: The hostname of your ClickHouse server
  • CLICKHOUSE_USER: The username for authentication
  • CLICKHOUSE_PASSWORD: The password for authentication

• Optional:

  • CLICKHOUSE_PORT: Default is 8443 if HTTPS is enabled, 8123 if disabled
  • CLICKHOUSE_SECURE: Default is "true"
  • CLICKHOUSE_VERIFY: Default is "true"
  • CLICKHOUSE_CONNECT_TIMEOUT: Default is "30"
  • CLICKHOUSE_SEND_RECEIVE_TIMEOUT: Default is "300"
  • CLICKHOUSE_DATABASE: Default is None

Example Configurations

• Local Development with Docker:

  CLICKHOUSE_HOST=localhost
   CLICKHOUSE_USER=default
   CLICKHOUSE_PASSWORD=clickhouse
   CLICKHOUSE_SECURE=false
   CLICKHOUSE_VERIFY=false
   

• ClickHouse Cloud:

  CLICKHOUSE_HOST=your-instance.clickhouse.cloud
   CLICKHOUSE_USER=default
   CLICKHOUSE_PASSWORD=your-password
   

• ClickHouse SQL Playground:

  CLICKHOUSE_HOST=sql-clickhouse.clickhouse.com
   CLICKHOUSE_USER=demo
   CLICKHOUSE_PASSWORD=