ClickHouse

MCP ClickHouse Tool

ClickHouse 向けのデフォルトで読み取り専用の Model Context Protocol (MCP) サーバーです。単一のツールセットのデプロイから、スキーマの検出、読み取り専用のクエリ、実行計画の分析、オプトインによる書き込み、プロファイルベースの複数サーバーへのアクセスを提供します。

読み取り専用は SQL テキストの照合ではなく、エンジンによって強制されます。クエリツールのクライアントには ClickHouse の readonly=1 が設定されるため、書き込み、外部テーブル関数、クエリレベルの SETTINGS は、クエリ対象のサーバーによって拒否されます。書き込みは別のツールに分離されており、プロファイルで要求されるまで登録されません。

要件： Python 3.13 以降、稼働中の ClickHouse インスタンス、環境変数または設定ファイルで指定した接続情報。

クイックスタート

DSN を設定し、MCP Inspector でサーバーを実行します。

# Option 1: Run directly with uvx (no clone needed)
export MCP_CLICKHOUSE_DSN="http://default:@localhost:8123/default"
npx -y @modelcontextprotocol/inspector@latest uvx mcp-clickhousex

# Option 2: Run from source (clone repo, then)
export MCP_CLICKHOUSE_DSN="http://default:@localhost:8123/default"
npx -y @modelcontextprotocol/inspector@latest uv run mcp-clickhousex

設定

プロファイルは、1つの ClickHouse 接続です。DSN と、その接続に適用される行数およびタイムアウトの上限で構成されます。default という名前のプロファイルは常に存在します。各ツールでは、別のプロファイルに接続するために省略可能な profile を指定でき、list_profiles で設定済みのプロファイルを確認できます。

設定は次の3つのソースから取得され、フィールドごとにマージされます。後のソースが優先されます。

1. ユーザー単位の config.json — 任意の数のプロファイルを設定できます。
2. MCP_CLICKHOUSE_PROFILES_<NAME>_<FIELD> 環境変数 — 任意の数のプロファイルを設定できます。
3. フラットな MCP_CLICKHOUSE_<FIELD> 環境変数 — default プロファイルのみを設定できます。

プロファイル単位ではなくフィールド単位でマージされるため、config.json に設定一式を記述したうえで、フラットな MCP_CLICKHOUSE_DSN によって default プロファイルをローカルサーバーに向け、他のフィールドはそのままにできます。3つのソースがいずれも存在しない場合、default は http://default:@localhost:8123/default にフォールバックします。

各設定のフィールド名は1つで、次の3通りの表記があります。MCP_CLICKHOUSE_<FIELD>、MCP_CLICKHOUSE_PROFILES_<NAME>_<FIELD>、または JSON キーとして小文字にしたフィールド名です。

上限はプロファイルごとに適用されます。上限を超える値は起動時に上限値に切り詰められます。整数でない値はデフォルトにフォールバックし、ブール値でない値の場合は ALLOW_WRITE がオフのままになります。

単一の接続： フラットな環境変数を使うのが最も手早い方法です。

# Connection DSN.
export MCP_CLICKHOUSE_DSN="http://user:password@host:8123/database"

# Optional description for the default profile (tooling/AI discovery).
export MCP_CLICKHOUSE_DESCRIPTION="Primary cluster"

# Optional caps, defaults shown.
export MCP_CLICKHOUSE_QUERY_MAX_ROWS="500"
export MCP_CLICKHOUSE_QUERY_COMMAND_TIMEOUT_SECONDS="30"
export MCP_CLICKHOUSE_SNAPSHOT_MAX_ROWS="10000"
export MCP_CLICKHOUSE_SNAPSHOT_COMMAND_TIMEOUT_SECONDS="120"

# Optional write access, off by default; also controls whether run_command
# is advertised at all.
export MCP_CLICKHOUSE_ALLOW_WRITE="false"
export MCP_CLICKHOUSE_WRITE_COMMAND_TIMEOUT_SECONDS="60"

複数の接続： ユーザー単位の config.json を使うと、ホストのプロセス環境に認証情報を置かずに済みます。

• Unix 系：~/.config/mcp-clickhousex/config.json
• Windows：%USERPROFILE%\.config\mcp-clickhousex\config.json

{
  "profiles": {
    "default": {
      "dsn": "http://default:@localhost:8123/default",
      "description": "Primary",
      "query_max_rows": 500,
      "query_command_timeout_seconds": 60,
      "snapshot_max_rows": 10000,
      "snapshot_command_timeout_seconds": 120
    },
    "warehouse": {
      "dsn": "http://user:pass@warehouse:8123/analytics",
      "description": "Warehouse"
    },
    "writer": {
      "dsn": "http://etl:pass@warehouse:8123/analytics",
      "description": "Warehouse, write-enabled",
      "allow_write": true,
      "write_command_timeout_seconds": 120
    }
  }
}

1つのプロファイルで読み取りと書き込みの両方を行うこともできますが、書き込みを有効にしたプロファイルを分ける構成がおすすめです。書き込み専用の DSN を用意できるため、書き込みに使う認証情報を実際に必要な権限に限定しつつ、読み取り用プロファイルは SELECT までの権限しかないログインのままにできます。

プロファイル名では大文字と小文字は区別されず、英数字のみを使用できます。構造化された環境変数の形式では _ で分割されるため、アンダースコアやハイフンは使用できません（MCP_CLICKHOUSE_PROFILES_WAREHOUSE_DSN は、プロファイルが warehouse、フィールドが DSN であることを示します）。規則に違反する名前は無視されます。また、config.json が存在しない、読み取れない、または {"profiles": {…}} の形式でない場合も無視されます。サーバーは失敗終了せず、残りのソースを使って起動します。

DSN の構文： scheme://user:password@host:port/database。https:// または clickhouses:// スキームを指定すると TLS が有効になり、クエリ文字列のパラメーターはドライバーに渡されます（?connect_timeout=10）。ただし readonly は例外で、サーバーがプロファイルの ALLOW_WRITE に基づいて常に最後に適用します。

ユーザー名またはパスワードに URL で予約されている文字が含まれる場合は、パーセントエンコードする必要があります — # → %23、? → %3F、/ → %2F、@ → %40、% → %25。ユーザー名 admin@org、パスワード p#ss? の場合は、http://admin%40org:p%23ss%3F@host:8123/database になります。

ツールとリソース

すべてのツールでは、オプションで profile を指定できます。省略した場合は、デフォルトのプロファイルが使用されます。

ツール

• types — EXPLAIN のバリエーション：plan（インデックス）、pipeline、syntax。デフォルトは plan と pipeline です。
• parameters — ドライバーのプレースホルダー（%(name)s または {name:Type}）に渡す名前付きパラメーターです。
• database — 修飾されていない名前に対するセッションのデフォルトデータベースです。それ以外の場合は db.table のように修飾してください。

カタログの探索専用ツールはありません。system.databases、system.tables、system.columns に対して run_query を使うと、データベース、テーブル、カラムを一覧表示し、サイズ（total_rows、total_bytes）とキー（primary_key、sorting_key、partition_key）を確認できます。これらのテーブルでは、SHOW で LIKE しか使えないのに対し、通常の WHERE 述語を使用できます。リスト表示ではわからないDDLを確認する場合は、SHOW が役立ちます。SHOW CREATE TABLE／VIEW／DICTIONARY を使うと、コーデック、TTL、カラム一覧全体を確認できます。

結果は RFC 4180 の CSV です。最初の行がヘッダーで、残りの行がデータです。NULL は ClickHouse 独自の CSV の null 表現である \N として出力されるため、空文字列と区別できます。

プランの Indexes セクションは、テーブルのキーに関する確定的な情報ではありません。クエリで使用されたキーのカラムのみを示すため、先頭のキー列をスキップするクエリでは、テーブルが実際に持つものより短いキーが報告されます。SHOW CREATE TABLE では同じ内容を説明するのに数百トークンを費やす一方、system.tables なら数十トークンで確認できるため、こちらで確認してください。

呼び出しに適用された行数上限は、結果とともに truncated および row_limit として返されます。

リソース

セキュリティ

このサーバーが開くすべてのクライアントには、ClickHouse 独自の readonly=1 が設定されるため、サーバーの SQL チェックだけでなくエンジン自体が次の操作を拒否します。

• あらゆる種類の書き込み（INSERT、DDL、ALTER … UPDATE、SYSTEM、GRANT）。
• 外部テーブル関数 url()、s3()、remote()、mysql() など。これにより、クエリが設定済みプロファイルの外部にあるホストへアクセスすることはできません。
• クエリレベルの SETTINGS。そのため、エージェントが指定する SQL によって行数と実行時間の上限を引き上げることはできず、INTO OUTFILE も拒否されます。

readonly=2 は意図的に使用していません。これは SETTINGS の変更を許可するため、これらの上限が単なる目安になってしまうからです。その代わり、無害なクエリ単位の調整（SETTINGS max_threads = …）も拒否されます。

さらに、run_query は SELECT／WITH … SELECT／SHOW のみを受け付け、analyze_query は最初の2つのみを受け付けます。どちらも1回の呼び出しにつき1つのステートメントです。対話型クエリには厳格な行数上限が適用されます（デフォルトは500、絶対上限は1 000）。より大きなデータを抽出するには、snapshot=true を使用してください（デフォルトは10 000、絶対上限は50 000）。

書き込みはオプトイン制で、オプトインされるまでは表示されません。 run_command は readonly=0 のクライアントで実行されるため、任意の DDL と DML を実行できます。また、readonly の制限が解除されることで、外部テーブル関数も再び使用できます。設定済みプロファイルのうち少なくとも1つで ALLOW_WRITE（デフォルトは false）が設定されない限り、このツールは登録されません。つまり、tools/list にも表示されないため、読み取り専用のデプロイではコンテキストを消費せず、エージェントが説得されて実行してしまうような書き込み手段も提供しません。いずれかのプロファイルがオプトインすると、ツールはサーバー全体に公開されますが、ロックされたままのプロファイルでは呼び出し時に引き続き拒否されます。list_profiles はプロファイルごとの allow_write を返すため、エージェントは書き込み可能なプロファイルを選択できます。

ALLOW_WRITE はアプリケーションレベルのソフトなガードであり、セキュリティ境界ではありません。制約するのはこのサーバーであって、データベースではありません。確実に読み取り専用にするには、ClickHouse への接続に SELECT だけが許可されたログインを使用し、書き込み可能なプロファイルには必要な権限だけに制限された認証情報を設定してください。run_command には destructive と openWorld のツールアノテーションが付与されているため、ホスト側で確認を必須にできますが、それらのアノテーションを尊重するかどうかはホスト次第です。ClickHouse にはロールバックできるトランザクションがありません。実行されたステートメントは、そのまま残ります。

接続認証情報には環境変数または設定ファイルを使用してください。シークレットをコミットしてはいけません。

MCP ホストの例

スニペットでは uvx mcp-clickhousex を使用します（クローンは不要です。uv が PATH にあることを確認してください）。必要に応じて接続情報を置き換えてください。DSN がすでに config.json または環境変数から取得される場合、env ブロックは不要です。

Claude Code と Cursor は同じ mcpServers 形式を読み込みます。

{
  "mcpServers": {
    "clickhouse": {
      "command": "uvx",
      "args": ["mcp-clickhousex"],
      "env": {
        "MCP_CLICKHOUSE_DSN": "http://default:@localhost:8123/default"
      }
    }
  }
}

[mcp_servers.clickhouse]
command = "uvx"
args = ["mcp-clickhousex"]

[mcp_servers.clickhouse.env]
MCP_CLICKHOUSE_DSN = "http://default:@localhost:8123/default"

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "clickhouse": {
      "type": "local",
      "enabled": true,
      "command": ["uvx", "mcp-clickhousex"],
      "environment": {
        "MCP_CLICKHOUSE_DSN": "http://default:@localhost:8123/default"
      }
    }
  }
}

{
  "inputs": [],
  "servers": {
    "clickhouse": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-clickhousex"],
      "env": {
        "MCP_CLICKHOUSE_DSN": "http://default:@localhost:8123/default"
      }
    }
  }
}

テスト

テストには ClickHouse インスタンスが稼働している必要があります。テストスイートはデフォルトデータベースにサンプルテーブルを作成してデータを投入し、その後削除します。

uv run pytest tests/ -v

ハーネスは MCP_TEST_CLICKHOUSE_DSN でインスタンスを特定し、設定されていない場合は http://admin:password123@localhost:8123/default を使用します。テスト対象を別のサーバーにするには、本番用の MCP_CLICKHOUSE_DSN を変更せずに、この値を設定してください。

テストスイートは同じインスタンス上に2つのプロファイルを設定します。読み取り専用の default と、書き込み可能な writable です。これにより、書き込みゲートの両方の動作を検証します。プロファイルがオプトインしているため run_command は公開されますが、オプトインしていないプロファイルに対しては引き続き拒否されます。

コントリビューション

Issue または PR を作成してください。既存のスタイルに従い、適宜テストを追加してください。

ライセンス

MIT