ClickHouse MCP Server

Overview

The ClickHouse MCP server enables Claude to connect directly to your ClickHouse database instances, allowing you to query data, explore database schemas, and analyze results without leaving your conversation. This integration bridges the gap between natural language interaction and powerful data analysis capabilities.

Installation

Prerequisites

• Python 3.13 or higher
• uv package manager (install via pip install uv or follow instructions at https://docs.astral.sh/uv/)
• Access to a ClickHouse database instance

Setup Instructions

1. Install the ClickHouse MCP package:

   pip install mcp-clickhouse
   

2. Configure Claude Desktop by editing the configuration file:

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

3. Add the ClickHouse MCP server configuration to your Claude Desktop config file:

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

4. Replace the placeholder values with your actual ClickHouse connection details.

5. For the command entry, replace "uv" with the absolute path to your uv executable if needed. On macOS, you can find this path using which uv.

6. Restart Claude Desktop to apply the changes.

Configuration Options

Required Environment Variables

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

Optional Environment Variables

• CLICKHOUSE_PORT: The port number (default: 8443 for HTTPS, 8123 for HTTP)
• CLICKHOUSE_SECURE: Enable/disable HTTPS connection (default: "true")
• CLICKHOUSE_VERIFY: Enable/disable SSL certificate verification (default: "true")
• CLICKHOUSE_CONNECT_TIMEOUT: Connection timeout in seconds (default: "30")
• CLICKHOUSE_SEND_RECEIVE_TIMEOUT: Send/receive timeout in seconds (default: "300")
• CLICKHOUSE_DATABASE: Default database to use (default: server default)

Security Considerations

• All queries are executed with readonly = 1 to ensure they are safe for your database.
• Use a dedicated read-only user for the MCP connection rather than an admin account.
• Consider using HTTPS (CLICKHOUSE_SECURE=true) and certificate verification (CLICKHOUSE_VERIFY=true) for production environments.

Demo Configuration

If you'd like to try the MCP with a public demo database, you can use the ClickHouse SQL Playground:

"env": {
  "CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
  "CLICKHOUSE_PORT": "8443",
  "CLICKHOUSE_USER": "demo",
  "CLICKHOUSE_PASSWORD": "",
  "CLICKHOUSE_SECURE": "true",
  "CLICKHOUSE_VERIFY": "true"
}

Usage Examples

Once configured, you can ask Claude to:

1. List available databases: "Show me all databases in my ClickHouse instance"

2. List tables in a specific database: "What tables are in the 'default' database?"

3. Run a SQL query: "Run this query: SELECT count() FROM system.tables"

4. Analyze query results: "Query the NYC taxi dataset and show me the average trip distance by hour of day"

Claude will execute these commands using the appropriate MCP tools and return the results directly in your conversation.