ClickHouse MCPサーバーでOLAP分析クエリを実行する

大量のログやイベントデータを溜め込んだClickHouseに対して、SQLを書かずに自然文のまま集計を投げたい場面は多いはずです。MCPを使えば、この橋渡しをAIエージェント側から自然に扱えます。ClickHouse公式組織が提供するMCPサーバーmcp-clickhouseはそのための実装で、PyPIパッケージとDocker Hubのmcp/clickhouseイメージ(公式配布、累計27万プル超)の両方で配布されており、既定では読み取り専用に固定されています。接続手順と、書き込みを許可するときの2段階のガード、ログ分析での実務的な使い方をまとめます。

mcp-clickhouseが提供するツール

現行バージョン(v0.6.0)が公開するツールは、ClickHouse本体向けとchDB向けに分かれます。

list_tablesはpage_tokenとpage_size(既定50件)によるページング、like/not_likeによるテーブル名フィルタ、詳細カラム情報を省く軽量モードに対応しています。テーブル数が多いクラスターでも、1回のレスポンスが肥大化しないよう設計されています。

ツールの応答はすべてJSON形式ですが、数値の扱いに1つ注意点があります。JavaScriptで安全に扱える整数の範囲(-9007199254740991〜9007199254740991)を超える整数は、精度を保つために10進数の文字列として返されます。クエリ結果の行データと、テーブルメタデータに含まれる整数(行数・バイト数など)の両方が対象です。ログ・イベント系のテーブルは行数がこの範囲を超えることも珍しくないため、集計結果を別のシステムに渡す場合はこの文字列化の挙動を踏まえておく必要があります。安全範囲内の整数と真偽値は、通常どおりのJSON型のまま返ります。

インストールと接続手順

uvを使う場合、Claude Desktopの設定ファイルにサーバー定義を追加します。

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": ["run", "--with", "mcp-clickhouse", "--python", "3.12", "mcp-clickhouse"],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_PORT": "<clickhouse-port>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_SECURE": "true"
      }
    }
  }
}

手元に接続先のクラスターが無くても試せます。ClickHouseが公開しているSQL Playgroundは、demoユーザー・パスワード空欄の設定で誰でも繋げる公開デモ環境です。

pip install mcp-clickhouse
# またはDockerイメージを使う
docker pull mcp/clickhouse

uvを使わずシステムのPythonで動かす場合は、インストール後にmcp-clickhouseコマンドをそのままcommandに指定する構成でも動作します。Python 3.10〜3.14に対応し、ローカル起動では3.12が推奨です。

既定は読み取り専用 — 書き込みは2段階のフラグで許可する

mcp-clickhouseはCLICKHOUSE_ALLOW_WRITE_ACCESS=falseが既定値です。探索目的の接続なら、この既定値を変えずに使うのが最も安全です。DDLやINSERTを許可したい場合だけ、明示的にtrueへ切り替えます。

書き込みを許可する運用では、MCPサーバー専用のClickHouseユーザーを作り、必要な権限だけを与えます。

CREATE USER mcp_agent IDENTIFIED BY '...';
GRANT SELECT, INSERT, CREATE TABLE, ALTER ADD COLUMN ON mydb.* TO mcp_agent;

このGRANTの範囲外のSQLは、MCPサーバー側のフラグ設定に関わらずサーバー側でACCESS_DENIEDとして弾かれます。max_table_size_to_dropやmax_partition_size_to_dropのようなClickHouse側の設定値も、被害範囲を制限する追加の手段として使えます。

HTTP/SSE接続時の認証

stdioトランスポート(既定)は標準入出力のみで通信するため認証を必要としませんが、HTTPまたはSSEトランスポートでは認証が必須です。3つのモードから選びます。

いずれも未設定のままHTTP/SSEトランスポートを起動すると、サーバーは起動に失敗します。ヘルスチェック用の/healthエンドポイントだけは意図的に認証対象外です。Bearerトークンが実際に機能しているかを確認したいときは、/healthではなく/mcpへ直接リクエストを投げ、Authorizationヘッダーの有無で401が返るかを見る必要があります。

OAuth / OIDCはFastMCPの組み込みプロバイダーに委譲する形で、社内で使っているIDプロバイダーに合わせて選びます。

Azure Entraを例にすると、環境変数はテナントID・クライアントID・クライアントシークレット・ベースURL・スコープの5つを設定します。

export FASTMCP_SERVER_AUTH=fastmcp.server.auth.providers.azure.AzureProvider
export FASTMCP_SERVER_AUTH_AZURE_TENANT_ID="<tenant-id>"
export FASTMCP_SERVER_AUTH_AZURE_CLIENT_ID="<client-id>"
export FASTMCP_SERVER_AUTH_AZURE_CLIENT_SECRET="<client-secret>"
export FASTMCP_SERVER_AUTH_AZURE_BASE_URL="https://mcp.example.com"

CLICKHOUSE_MCP_AUTH_TOKENや個々のプロバイダー変数は、プロセスの環境変数として直接設定した値が最優先されます。パッケージディレクトリから遡って見つかる.envファイルはFASTMCP_SERVER_AUTH自体を含め認証プロバイダーの再選択ができ、作業ディレクトリの互換用.envは不足しているプロバイダー設定値を補うだけです。.envファイル、特にパッケージ側の.envへの書き込み権限は、認証設定そのものと同じ重みで扱う必要があります。

chDBで埋め込みエンジンとして使う

run_chdb_select_queryは、独立したクラスターを持たずに使えるchDBの組み込みエンジンを呼び出します。ファイル・URL・別のデータベースに対して、ETLの前処理なしで直接SQLを投げられるのが特徴です。オプション拡張のため、pip install 'mcp-clickhouse[chdb]'でインストールし、CHDB_ENABLED=trueを設定します。

ClickHouseとchDBは同時に有効化できます。稼働中のクラスターに繋ぎながら、手元のCSVファイルもその場で分析するといった構成が1つのサーバーで済みます。

"env": {
  "CLICKHOUSE_HOST": "<clickhouse-host>",
  "CLICKHOUSE_USER": "<clickhouse-user>",
  "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
  "CHDB_ENABLED": "true",
  "CHDB_DATA_PATH": "/path/to/chdb/data"
}

この構成では、Claudeが状況に応じてrun_query(クラスター側)とrun_chdb_select_query(chDB側)のどちらを呼ぶか自分で判断します。「このCSVとクラスター上のテーブルを突き合わせて」のような依頼でも、片方だけに接続を絞っている場合よりも自然に処理が進みます。

ログ・イベントデータを自然文で分析する

ClickHouseが向いているのは、行数が数億〜数十億に達するログ・イベント系のテーブルです。テーブル構造さえlist_tablesで把握できれば、あとは自然文で聞くだけで済みます。

過去24時間でHTTPステータス500が一番多かったエンドポイントを教えて

ユーザーごとのイベント数を日次で集計して、急増しているユーザーを見つけて

裏側ではrun_queryが集計クエリを組み立てて実行します。大規模テーブルへの集計はClickHouseの列指向エンジンが得意とする領域そのもので、通常のRDBMSでは時間のかかる全走査集計も現実的な時間で返ってきます。読み取り専用の既定値のままなら、集計を試行錯誤しても元データを壊す心配がありません。

分析基盤MCPサーバーの使い分け早見表

BigQueryとの接続はClaude BigQuery連携、ローカル完結の分析基盤はDuckDB / MotherDuck MCPサーバーで扱っています。同じログデータでも、集計・OLAP用途ならClickHouse、キーワードでの全文検索や横断的な調査ならElasticsearch MCPサーバーというように、聞きたい質問の種類で使い分けます。「このエラーメッセージを含むログを全部探して」のような検索寄りの質問はElasticsearch側が得意で、「時間帯別のエラー率を集計して」のような集計寄りの質問はClickHouse側が得意です。

よくあるつまずき

• list_tablesが途中で止まったように見える: page_tokenはone-time利用で約1時間で失効する。時間を置きすぎると次ページの取得に失敗するので、続けて取得する
• 書き込みを許可したのにDROPが通らない: CLICKHOUSE_ALLOW_WRITE_ACCESS=trueだけでは足りず、破壊的操作にはCLICKHOUSE_ALLOW_DROP=trueも必要
• HTTP接続で毎回401になる: CLICKHOUSE_MCP_AUTH_TOKENを設定しても、クライアント側のAuthorization: Bearer <token>ヘッダーが抜けていると認証が通らない
• chDBのクエリでモジュールエラーが出る: chdbエクストラをインストールせずにCHDB_ENABLED=trueだけ設定している。pip install 'mcp-clickhouse[chdb]'でchdbパッケージ自体を入れる

よくある質問

認証を一時的に無効化してテストできますか

CLICKHOUSE_MCP_AUTH_DISABLED=trueで無効化できますが、ローカル開発限定の設定です。あわせてCLICKHOUSE_MCP_ALLOWED_HOSTSで許可ホストを127.0.0.1などに絞ります。ネットワークに公開されたサーバーでこの設定を使うのは避けます。

ヘルスチェックはどう確認しますか

HTTPまたはSSEトランスポートで起動している場合、/healthにGETまたはHEADでアクセスすると、ClickHouseに接続できていれば200 OK(本文OK)、接続できなければ503が返ります。Kubernetesのliveness/readinessプローブのように認証なしで叩ける設計で、ロードバランサーからのヘルスチェックにもそのまま使えます。

chDBだけを使い、通常のClickHouseクラスターには繋がない構成もできますか

できます。CHDB_ENABLED=trueかつCLICKHOUSE_ENABLED=falseにすれば、クラスターへの接続情報を用意せずchDBの組み込みエンジンだけで動かせます。手元のファイル分析だけが目的で、常設のクラスターを持たないチームに向く構成です。

まとめ

mcp-clickhouseはPyPIとDocker Hubの両方で配布される公式MCPサーバーで、既定では読み取り専用のため探索的な分析から安全に始められます。書き込みを許可する場合はCLICKHOUSE_ALLOW_WRITE_ACCESSとCLICKHOUSE_ALLOW_DROPの2段階フラグに加え、MCPサーバー専用のClickHouseユーザーにGRANTで権限を絞ることが実質的な防御になります。列指向エンジンの強みが最も出るのは数億行規模のログ・イベントデータの集計で、list_tablesでテーブル構造を把握してしまえば、あとは自然文で集計を頼めます。chDBを組み合わせれば、クラスターを立てずに手元のファイルもその場で分析できます。