ClickHouse MCP を触ってみた - SO Technologies 開発者ブログ

こんにちは。SREの平です。今回は自然言語で ClickHouse を操作できる MCP を触ってみました。

これは、LLM（今回は Claude）と ClickHouse をつなぐインターフェースであり、SQLを知らないユーザーでも自然言語でデータベースを操作できるのが特徴です。本記事では、ローカル環境での導入と実行、初期の挙動、LLMとのやりとり、デモデータを使った応用を見てみたいと思います。

■　公式github

https://github.com/ClickHouse/mcp-clickhouse

■　検証環境

項目	内容
OS	Windows 11
クライアント	Claude for Desktop
サーバー	WSL(ubuntu)上に mcp-clickhouse をインストール、起動
ClickHouse	自宅（バージョン 23.3）/ 公式デモサーバー
DB内容	自宅：ゲームデータ（会社名・ゲーム名・価格） / 公式：Hacker News等

■　環境の準備

ClickHouse

まずはClickHouseです。今回は自宅にクラスターがあるのでそれを利用しました。なおDBの用意がない方用に、公式がデモ用Clickhouseサーバーを用意してくれていますのでそちらをありがたく利用しましょう。

対象	自宅クラスター	公式デモ
HOST	clickhouse.local.xxx.xxx	sql-clickhouse.clickhouse.com
USER	taira	demo
PASS	taira1234	無し
PORT	8123	-

これらを後ほど Claude for Desktop に設定しますが、一旦先に行きましょう。

MCPのインストールです。変わる可能性があるので公式をご覧いただきたいのですが、現状uvとpipを使う方法があるようで、今回はpipを使いました。

pip install --upgrade mcp-clickhouse

Claude for Desktop

次に Claude for Desktop を用意し、MCPの設定ファイルを編集します。パスは公式にも記載がありますが Claude for Desktop から ファイル > 設定 > 開発者 > 構成を編集 > 「claude_desktop_config.json」 でも開けます。

そしてClickhouseのサーバー情報等を以下のように記述します。

自宅クラスターの場合（もちろん各数値は各自の環境に合わせて書き換えてください）

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "wsl",
      "args": [
        "bash",
        "-c",
        "CLICKHOUSE_HOST=clickhouse.local.xxx.xxx CLICKHOUSE_USER=taira CLICKHOUSE_PASSWORD=taira1234 CLICKHOUSE_PORT=8123 CLICKHOUSE_SECURE=false CLICKHOUSE_VERIFY=false CLICKHOUSE_MCP_SERVER_TRANSPORT=stdio CLICKHOUSE_MCP_BIND_HOST=localhost CLICKHOUSE_MCP_BIND_PORT=8000 python3 -m mcp_clickhouse.main"
      ]
    }
  }
}

公式デモサイトの場合

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "wsl",
      "args": [
        "bash",
        "-c",
        "CLICKHOUSE_HOST=sql-clickhouse.clickhouse.com CLICKHOUSE_USER=demo CLICKHOUSE_PASSWORD= CLICKHOUSE_MCP_SERVER_TRANSPORT=stdio CLICKHOUSE_MCP_BIND_HOST=localhost CLICKHOUSE_MCP_BIND_PORT=8000 python3 -m mcp_clickhouse.main"
      ]
    }
  }
}

これで環境は整いました。

■　起動直後のMCPの挙動

Claudeと接続すると、MCPは以下のように自律的にClickHouseに問い合わせを開始しました。ま、tools/listから順に実行という流れですね。

タイミング	アクション	意図
接続直後	tools/list	使用可能なツール一覧取得
接続直後	list_databases	DB一覧取得
DB取得後	list_tables	テーブル一覧取得
テーブル取得後	run_select_query など	内容に応じたクエリ実行

そして「game_db が面白そうですね。中身を見ますか？」と提案され、"yes" と返すと自動的にクエリを投げてくれます。その他、以下のような自然言語プロンプトに対し、1発で正しいSQLが生成されました。

「メーカー別のゲーム本数は？」
「全ゲームの合計金額は？」

さらに「グラフで見せて」と指示すると、棒グラフや円グラフも自動生成されました。素晴らしい。

■　バージョン依存のエラーも自動回避

以下のような若干古い ClickHouse 側のバージョン差によるエラーも自動で検知・対処されました。エラーが起きにくいですが、なるべくClickHouseは新しくしておいた方が手戻りは少ないでしょう。

Error calling tool 'list_tables': HTTPDriver for http://clickhouse.local.xxx.xxx:8123 received ClickHouse error code 47
 Code: 47. DB::Exception: Missing columns: 'total_bytes_uncompressed' while processing query:

■　安全なクエリ

実際にMCPが発行しているクエリを確認すると以下のような特徴があり、サーバーの負荷を減らし、データを保護しつつ、網羅的にデータを引っ張るような努力が垣間見れました。素晴らしいですね。ただこれらに依存せず、なるべく読み込み権限のみのユーザーや、閲覧できるデータベースを制限するなど、できるところはやっておきたいですね。

SELECT * FROM viewIfPermitted ... などで権限が無いならNullを返し、エラーにしにくくしている。
関数名、フォーマット名、エンジン名、設定名などを一括取得して、LLMが「正しい用語」を使って応答できるよう準備している。
多くの列を一度に取得しつつも、全体の量には上限をかけてサーバーを安全に運用する配慮も見えた。

■　より大規模な検証

大規模データでの動作確認のため、ClickHouse公式のデモサーバーに接続してみましょう。大量のデータがありますが、そのうち Hacker Newsデータを使ってみます。なお、ここが今回の目玉です。

「Hacker Newsから、最近の攻撃手法ランキングを出して」
「アクセス数の推移をグラフで」

といったプロンプトで、数十秒で以下のレポートが作成されました。感動です。

■　セキュリティ観点

自然言語で任意のSQLが投げられるため、ユーザーやテナントごとに分離が必要な場合は Row Policy などを検討してみてはいかがでしょうか。

■　最後に

ClickHouse MCPは、自然言語 × データベースの可能性を大きく広げるプロジェクトです。

導入は簡単、WSL環境でもすぐに試せる
Claudeとの組み合わせで、高精度なSQL生成と可視化が可能
実運用にはセキュリティの設計が不可欠

今後は、以下のような発展が期待されます

独自ツールの追加（例：登録・更新用のwrite系クエリ）
他LLM（ChatGPTなど）への対応
より柔軟なデータ可視化機能との連携

ぜひ試してみてください、もっとデータをClickHouseに入れたくなるはずです。

■ 公式github

■ 検証環境

■ 環境の準備

■ 起動直後のMCPの挙動

■ バージョン依存のエラーも自動回避

■ 安全なクエリ

■ より大規模な検証

■ セキュリティ観点

■ 最後に