Clickhouse

🚀 ClickHouse MCP Server

A MCP server project based on the ClickHouse database, which provides tools for database connection and query execution.

🚀 Quick Start

Installation

Claude Desktop

MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "clickhouse-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/burakdirin/Projects/clickhouse-mcp-server",
        "run",
        "clickhouse-mcp-server"
      ],
      "env": {
        "CLICKHOUSE_HOST": "localhost",
        "CLICKHOUSE_USER": "root",
        "CLICKHOUSE_PASSWORD": "password",
        "CLICKHOUSE_DATABASE": "[optional]",
        "CLICKHOUSE_READONLY": "true"
      }
    }
  }
}

{
  "mcpServers": {
    "clickhouse-mcp-server": {
      "command": "uvx",
      "args": [
        "clickhouse-mcp-server"
      ],
      "env": {
        "CLICKHOUSE_HOST": "localhost",
        "CLICKHOUSE_USER": "root",
        "CLICKHOUSE_PASSWORD": "password",
        "CLICKHOUSE_DATABASE": "[optional]",
        "CLICKHOUSE_READONLY": "true"
      }
    }
  }
}

Installation via Smithery

To automatically install the ClickHouse database integration server for running on Claude Desktop through Smithery:

npx -y @smithery/cli install @burakdirin/clickhouse-mcp-server --client claude

✨ Features

This server provides two tools:

• connect_database: Connect to a specific ClickHouse database
  • database parameter: The name of the database to connect to (string)
  • Returns a confirmation message upon successful connection
• execute_query: Execute ClickHouse queries
  • query parameter: The SQL query/multiple queries to execute (string)
  • Returns the query results in JSON format
  • Multiple queries can be sent separated by semicolons

📦 Installation

You can install the package using the uv command:

uv pip install clickhouse-mcp-server

Or use pip:

pip install clickhouse-mcp-server

🔧 Technical Details

The server uses the following environment variables:

📚 Documentation

Build and Release

To prepare the package for distribution:

1. Synchronize dependencies and update the lock file:

uv sync

2. Build the distribution:

uv build

This will create source and wheel format distributions in the dist/ directory. 3. Publish to PyPI:

uv publish

Note: You need to set your PyPI credentials via environment variables or command-line arguments:

• Token: --token or UV_PUBLISH_TOKEN
• Or username/password: --username/UV_PUBLISH_USERNAME and --password/UV_PUBLISH_PASSWORD

Debugging

Since the MCP server runs through standard input and output, debugging can be challenging. For the best debugging experience, we highly recommend using MCP Inspector. You can start the MCP Inspector with the following command:

npx @modelcontextprotocol/inspector uv --directory /Users/burakdirin/Projects/clickhouse-mcp-server run clickhouse-mcp-server

After starting, the Inspector will display a URL that you can access in your browser to start debugging.