ClickHouse Cloud のリモートMCPサーバーを有効にして接続する

このガイドでは、ClickHouse Cloud リモートMCPサーバーを有効にし、一般的な開発ツールで使用できるよう設定する方法を説明します。 前提条件

稼働中のClickHouse Cloud サービス
使用する IDE またはエージェント型開発ツール
ヘッドレス認証を行う場合は、必要な組織およびサービスへのアクセス権を持つ ClickHouse Cloud API キー

Cloud でリモートMCPサーバーを有効にする

リモートMCPサーバーを有効にする対象の ClickHouse Cloud サービスに接続します。左側のメニューで Connect をクリックします。接続の詳細が表示されたボックスが開きます。 Connect with MCP を選択します。サービスで MCP を有効にするには、ボタンをオンにします。MCP を有効化または無効化するには、control-plane:service:manage-mcp アクセス許可が必要です (Console roles and permissions を参照) 。表示された URL をコピーします。これは以下の URL と同じです。

https://mcp.clickhouse.cloud/mcp

開発用にリモートMCPをセットアップする

以下からお使いのIDEまたはツールを選択し、対応するセットアップ手順に従ってください。

ヘッドレス環境からの認証

MCP クライアントがリモートホストやヘッドレスホスト上で動作しており、ブラウザベースの OAuth フローを利用するのが現実的でない場合は、代わりに ClickHouse Cloud API キーを使用して認証します。

ClickHouse Cloud コンソールで対象の組織を開き、API Keys を選択します。
MCP クライアントがアクセスする組織およびサービスに必要な、最小限のロールとアクセス許可を付与したキーを作成し、キー ID とシークレットをダウンロードします。
リモートホスト上で、シークレット管理システムを通じて認証情報を渡し、HTTP Basic 認証の値を作成します。

export CLICKHOUSE_CLOUD_API_KEY="<key_id>"
export CLICKHOUSE_CLOUD_API_SECRET="<key_secret>"

export CH_AUTH="Basic $(
  printf '%s:%s' \
    "$CLICKHOUSE_CLOUD_API_KEY" \
    "$CLICKHOUSE_CLOUD_API_SECRET" |
  base64 | tr -d '\n'
)"

MCPクライアントを選択し、リモートMCPサーバーを追加します。

Claude Code
Codex
OpenCode

claude mcp add \
  --scope user \
  --transport http \
  clickhouse-cloud \
  https://mcp.clickhouse.cloud/mcp \
  --header 'Authorization: ${CH_AUTH}'

Claude Code は接続時に環境変数の CH_AUTH を展開します。Claude Code を起動して /mcp を実行し、clickhouse-cloud が接続されていることを確認してください。リモートHTTPサーバーとヘッダーの設定の詳細については、Claude Code の MCP ドキュメントを参照してください。

~/.codex/config.toml に次のエントリを追加します。

[mcp_servers.clickhouse-cloud]
url = "https://mcp.clickhouse.cloud/mcp"
env_http_headers = { Authorization = "CH_AUTH" }

codex mcp list を実行し、clickhouse-cloud が設定されていることを確認してください。mcp_servers.<id>.env_http_headers の詳細については、Codex の設定リファレンスを参照してください。

opencode.jsonc 設定ファイルに次のエントリを追加します。

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "clickhouse-cloud": {
        "type": "remote",
        "url": "https://mcp.clickhouse.cloud/mcp",
        "oauth": false,
        "headers": {
          "Authorization": "{env:CH_AUTH}"
        }
      }
    }
  }
}

opencode mcp list を実行し、clickhouse-cloud が接続されていることを確認してください。リモートサーバー、ヘッダー、環境変数の置換の詳細については、OpenCode の MCP ドキュメントを参照してください。

各クライアントのセッションで CH_AUTH を参照できる状態にしておいてください。また、API キー、シークレット、CH_AUTH の値はソース管理にコミットしないでください。Base64 エンコードは認証情報を暗号化するものではありません。この API キーによる方式では、ブラウザも、clickhousectl での別途ログインも必要ありません。

Claude Code

作業ディレクトリで次のコマンドを実行し、ClickHouse Cloud MCPサーバーの設定をClaude Codeに追加します。

claude mcp add --transport http clickhouse-cloud https://mcp.clickhouse.cloud/mcp

続いて、Claude Code を起動します。

claude

MCPサーバーを一覧表示するには、次のコマンドを実行します。

/mcp

clickhouse-cloud を選択し、ClickHouse Cloud の認証情報を使って OAuth 認証を行います。

Claude web UI

Customize > Connectors に移動します
「+」アイコンをクリックし、Add custom connector を選択します
カスタムコネクタに clickhouse-cloud などの名前を付けて追加します
新しく追加した clickhouse-cloud コネクタをクリックし、Connect をクリックします
OAuth を使用して、ClickHouse Cloud の認証情報で認証します

Cursor

Cursor Marketplace でMCPサーバーを探してインストールします。
ClickHouse を検索し、任意のサーバーで「Add to Cursor」をクリックしてインストールします
OAuth で認証します。

Visual Studio Code

以下の設定を .vscode/mcp.json に追加します。

{
  "servers": {
    "clickhouse-cloud": {
      "type": "http",
      "url": "https://mcp.clickhouse.cloud/mcp"
    }
  }
}

詳細については、Visual Studio Code ドキュメントを参照してください。

Windsurf

以下の設定でmcp_config.jsonファイルを編集してください。

{
  "mcpServers": {
    "clickhouse-cloud": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.clickhouse.cloud/mcp"]
    }
  }
}

詳しくは、Windsurf docsを参照してください。

Zed

ClickHouse をカスタムサーバーとして追加します。 Zed の設定の context_servers に、以下を追加します。

{
  "context_servers": {
    "clickhouse-cloud": {
      "url": "https://mcp.clickhouse.cloud/mcp"
    }
  }
}

その後、Zed が初めてサーバーに接続する際に、OAuth による認証を求められるはずです。詳しくは、Zed のドキュメントを参照してください。

Codex

CLIでClickHouse Cloud MCPサーバーを追加するには、次のコマンドを実行します。

codex mcp add clickhouse-cloud --url https://mcp.clickhouse.cloud/mcp

使用例

接続したら、自然言語のプロンプトを使って ClickHouse Cloud を操作できます。以下では、一般的なワークフローと、その際に MCPクライアントがバックグラウンドで呼び出すツールを紹介します。利用可能なツールの一覧については、ツールリファレンスを参照してください。

データの探索

まず、何が利用できるかを確認しましょう。

プロンプト	呼び出されるツール
”アクセスできる組織はどれですか？“	`get_organizations`
”自分のサービスで利用できるデータベースは何ですか？“	`list_databases`
”`default` データベース内のテーブルを表示してください”	`list_tables`
”名前が `events_` で始まるテーブルをすべて一覧表示してください”	`list_tables` (`like` フィルタを使用)

分析クエリの実行

自然言語で質問すると、エージェントがそれを SQL に変換します。

プロンプト	呼び出されるツール
”`hits` テーブルの先頭 10 行を表示して”	`run_select_query`
”過去 7 日間の国別の平均セッション時間は?”	`run_select_query`
”`analytics` データベースの各テーブルには何行ありますか?”	`run_select_query`

run_select_query ツールで許可されているのは SELECT ステートメントのみです。すべてのクエリは読み取り専用です。

サービスとインフラストラクチャの管理

ClickHouse Cloud リソースの状況を把握できます。

プロンプト	呼び出されるツール
”すべてのサービスを一覧表示して”	`get_services_list`
”本番サービスのステータスは？“	`get_service_details`
”このサービスのバックアップスケジュールを表示して”	`get_service_backup_configuration`
”最近のバックアップを一覧表示して”	`list_service_backups`
”このサービスで設定されている ClickPipes は？“	`list_clickpipes`

コストの監視

プロンプト	呼び出されるツール
「先週の組織のコストはいくらでしたか？」	`get_organization_cost`
「3月1日から3月15日までの日次コストを表示して」	`get_organization_cost` (`from_date` と `to_date` を指定)

ClickHouse Agent Skills

はじめる

サービスとインフラストラクチャ

Bring Your Own Cloud

データとインテグレーション

接続とクエリ実行

アクセス管理

セキュリティとコンプライアンス

監視とバックアップ

AI ツールとエージェント

Cloud API

請求

サポート

ClickHouse Private

ClickHouse Cloud のリモートMCPサーバーを有効にして接続する

Cloud でリモートMCPサーバーを有効にする

開発用にリモートMCPをセットアップする

ヘッドレス環境からの認証

Claude Code

Claude web UI

Cursor

Visual Studio Code

Windsurf

Zed

Codex

使用例

データの探索

分析クエリの実行

サービスとインフラストラクチャの管理

コストの監視

​Cloud でリモートMCPサーバーを有効にする

​開発用にリモートMCPをセットアップする

​ヘッドレス環境からの認証

​Claude Code

​Claude web UI

​Cursor

​Visual Studio Code

​Windsurf

​Zed

​Codex

​使用例

​データの探索

​分析クエリの実行

​サービスとインフラストラクチャの管理

​コストの監視

​関連コンテンツ

Cloud でリモートMCPサーバーを有効にする

開発用にリモートMCPをセットアップする

ヘッドレス環境からの認証

Claude Code

Claude web UI

Cursor

Visual Studio Code

Windsurf

Zed

Codex

使用例

データの探索

分析クエリの実行

サービスとインフラストラクチャの管理

コストの監視

関連コンテンツ