ClickHouse/mcp-clickhouse

解決する問題

このプロジェクトは、AI アシスタント（Claude Desktop など）が ClickHouse データベースと直接対話できるようにする Model Context Protocol (MCP) サーバーを提供します。LLM と ClickHouse に保存された構造化データの間のギャップを埋め、ユーザーが手動でファイルをエクスポートしたり、すべてのクエリを自分で書いたりすることなく、AI がデータをクエリ、探索、分析できるようにします。

仕組み

このサーバーは、特定の ClickHouse ツールを MCP 互換クライアントに公開する仲介役として機能します。リモートの ClickHouse クラスターに接続するか、ETL プロセスなしでファイルや URL からデータをクエリするための組み込み ClickHouse エンジンである chDB を使用する、2 つの操作モードをサポートしています。

主な機能は次のとおりです。

• クエリ実行：SQL インジェクションを防ぎ、複雑な型を処理するための名前付きパラメータをサポートした SQL クエリを実行します。
• データベース探索：データベースとテーブルを一覧表示（ページネーションとフィルタリング付き）して、AI がスキーマを理解するのに役立てます。
• クエリ検査：DESCRIBE を使用して結果スキーマを確認し、EXPLAIN ESTIMATE を使用して実行前にクエリのリソースコストを予測します。
• セキュリティ：デフォルトで読み取り専用モードを実装し、HTTP/SSE トランスポート用に複数の認証方法（静的 Bearer トークンまたは OAuth/OIDC）を提供します。

対象読者

• データアナリストとエンジニア：AI を使用して ClickHouse の大規模データセットを探索したい方。
• AI アプリケーション開発者：LLM エージェントに ClickHouse データベースからのリアルタイムデータ取得機能を提供したい方。
• DevOps エンジニア：ClickHouse データアクセスを MCP ベースの AI エコシステムに統合する必要がある方。

ハイライト

• デュアルエンジンサポート：完全な ClickHouse クラスターと組み込み chDB エンジンの両方で動作します。
• 安全な探索：デフォルトの読み取り専用アクセスと、高コストなスキャンを防ぐためのクエリコスト見積もりツール。
• 安全なパラメータ化：{name:Type} プレースホルダーを使用して、安全かつ正確なデータバインディングを実現。
• エンタープライズ対応認証：FastMCP を介して幅広い OIDC プロバイダーをサポートし、本番環境での展開に対応。