Clickhouse MCP server

Clickhouse MCP サーバー

Clickhouse データベース用の MCP サーバープロジェクトです。

インストール

uv を使用してパッケージをインストールできます。

uv pip install clickhouse-mcp-server

または、pip を使用します。

pip install clickhouse-mcp-server

コンポーネント

ツール

サーバーは 2 つのツールを提供します。

• connect_database：特定の Clickhouse データベースに接続します

  • database パラメーター：接続先のデータベース名（文字列）
  • 接続に成功すると確認メッセージを返します

• execute_query：Clickhouse クエリを実行します

  • query パラメーター：実行する SQL クエリ（複数可）（文字列）
  • クエリ結果を JSON 形式で返します
  • セミコロンで区切ることで、複数のクエリを送信できます

設定

サーバーでは、以下の環境変数を使用します。

• CLICKHOUSE_HOST：Clickhouse サーバーのアドレス（デフォルト："localhost"）
• CLICKHOUSE_USER：Clickhouse のユーザー名（デフォルト："root"）
• CLICKHOUSE_PASSWORD：Clickhouse のパスワード（デフォルト：" "）
• CLICKHOUSE_DATABASE：初期データベース（任意）
• CLICKHOUSE_READONLY：読み取り専用モード（有効にするには 1/true を設定します。デフォルト：false）

クイックスタート

インストール

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

Smithery 経由でインストール

Smithery 経由で、Claude Desktop 用の Clickhouse Database Integration Server を自動的にインストールするには、以下を実行します。

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

開発

ビルドと公開

配布用のパッケージを準備するには、以下を実行します。

1. 依存関係を同期し、ロックファイルを更新します。

uv sync

2. パッケージの配布物をビルドします。

uv build

これにより、dist/ ディレクトリにソース配布物と wheel 配布物が作成されます。

3. PyPI に公開します。

uv publish

注：環境変数またはコマンドフラグを使って、PyPI の認証情報を設定する必要があります。

• トークン：--token または UV_PUBLISH_TOKEN
• または、ユーザー名／パスワード：--username／UV_PUBLISH_USERNAME および --password／UV_PUBLISH_PASSWORD

デバッグ

MCP サーバーは stdio 経由で実行されるため、デバッグが難しい場合があります。最適なデバッグ環境を利用するため、MCP Inspector の使用を強くおすすめします。

次のコマンドを使い、npm 経由で MCP Inspector を起動できます。

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

起動すると、Inspector に URL が表示されます。この URL にブラウザーからアクセスすると、デバッグを開始できます。