Clickhouse

🚀 ClickHouse MCP サーバー

ClickHouse データベースをベースにした MCP サーバープロジェクトです。

🚀 クイックスタート

インストール

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 データベース統合サーバーを自動インストールするには：

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

✨ 主な機能

このサーバーは、ClickHouse データベースとの接続やクエリの実行などの機能を提供します。具体的には、以下の 2 つのツールを提供しています。

📦 インストール

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

uv pip install clickhouse-mcp-server

または pip を使用します：

pip install clickhouse-mcp-server

💻 使用例

基本的な使用法

このサーバーは 2 つのツールを提供しています：

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

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

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

  • query パラメータ：実行する SQL クエリ/複数のクエリ（文字列）
  • JSON 形式のクエリ結果が返されます。
  • 複数のクエリはセミコロンで区切って送信できます。

📚 ドキュメント

設定

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

開発

パッケージのビルドと公開

パッケージを配布できるように準備するには：

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

uv sync

2. リリース版をビルドします：

uv build

これにより、dist/ ディレクトリにソースコードとホイール形式のリリース版が作成されます。

3. PyPI に公開します：

uv publish

注意: PyPI の認証情報を環境変数またはコマンドライン引数で設定する必要があります：

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

デバッグ

MCP サーバーは標準入出力で動作するため、デバッグは難しい場合があります。最適なデバッグ体験を得るために、MCP Inspector の使用を強くおすすめします。

以下のコマンドで MCP Inspector を起動できます：

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

起動後、Inspector は URL を表示し、ブラウザでその URL にアクセスしてデバッグを開始できます。