MCP 経由で ClickHouse を Cursor に接続する方法

💡 インストール不要? cloud.anythingmcp.com を直接利用してください。 サインインし、Connectors → ClickHouse をクリック、認証情報を貼り付け、MCP API キーを発行すれば完了です。Docker も git clone もローカルサーバーも不要。

ClickHouse + Cursor

あらゆる AI エージェントから、HTTP インターフェース経由で ClickHouse サーバーや ClickHouse Cloud サービスを読み取り専用で照会できます。データベース、テーブル、カラムの一覧、CREATE 文の参照、テーブルサイズの確認、実行中と直近のクエリの確認、任意の SELECT の実行。すべてのリクエストに readonly=1 が付くため、書き込みは ClickHouse 自身が拒否します。

前提条件

完全なセットアップ手順はコネクタ自体に組み込まれています (ストアでコネクタを選択すると表示)。必要な環境変数:

CLICKHOUSE_URL, CLICKHOUSE_USER, CLICKHOUSE_PASSWORD

ステップ 1 — 認証情報を取得

設定は約 3 分です。ClickHouse サーバーまたは ClickHouse Cloud サービスの HTTPS アドレスと、読み取りのできるユーザーが必要です。

1. HTTP インターフェースのアドレスをポート付きで CLICKHOUSE_URL に入力します。ClickHouse Cloud ではサービスを開き、Connect をクリックして HTTPS を選び、ホストをコピーします（例: https://abc123xyz.europe-west4.gcp.clickhouse.cloud:8443）。セルフホストの場合は https://your-host:8443、プライベートネットワーク内なら http://your-host:8123 です。スキーム、ホスト、ポートのみで、パスは付けません。
2. 読み取りしかできない専用ユーザーを作成します。例: CREATE USER mcp_reader IDENTIFIED BY '...'; GRANT SELECT ON analytics.* TO mcp_reader;。clickhouse_table_sizes、clickhouse_running_queries、clickhouse_recent_queries を使うなら、GRANT SELECT ON system.parts, system.processes, system.query_log TO mcp_reader も付与します。ClickHouse Cloud の組み込みユーザーは default です。
3. このユーザーに readonly = 2 の設定プロファイルを割り当てないでください。コネクタはリクエストごとに readonly=1 を設定しますが、readonly = 2 のもとでは ClickHouse がこの変更を拒否します。readonly = 0 と 1 はどちらも動作します。
4. ユーザー名を CLICKHOUSE_USER に、パスワードを CLICKHOUSE_PASSWORD に入力します。HTTP Basic 認証として送信されます。
5. ClickHouse Cloud のみ: サービスの IP access list で、AnythingMCP の接続元アドレスを許可しておく必要があります。
6. コネクタをインストールし、clickhouse_server_info を実行します。バージョン、稼働時間、サーバーのタイムゾーン、接続ユーザー、その既定データベース、実効の readonly レベルが表示されます。

読み取る内容: ユーザーから見えるデータベース（エンジンとコメント付き）、1 つのデータベースのテーブルとビュー（エンジン、総行数と総バイト数、読みやすいサイズ、コメント）、テーブルのカラム（型、デフォルト式、パーティションキー・ソートキー・主キーに含まれるか）、テーブルやビューの CREATE 文（エンジン、ORDER BY、PARTITION BY、TTL、設定、またはビューの元になる SELECT）、そして clickhouse_search_columns で全データベースから名前で探したカラムです。運用面では、アクティブなパーツから見たテーブルごとのストレージ、実行中のクエリ、クエリログの完了または失敗したクエリを読み取ります。clickhouse_query は SELECT、WITH、SHOW、DESCRIBE、EXPLAIN、EXISTS のいずれか 1 文を実行します。

書き込む内容: ありません。すべてのリクエストに readonly=1 の設定が付くため、ユーザーの権限にかかわらず ClickHouse は INSERT、ALTER、CREATE、DROP、SET を拒否します。書き込みツールがないので、インストール時にオフになっているツールもありません。

AI の照会の進め方: clickhouse_list_databases、clickhouse_list_tables、clickhouse_describe_table、clickhouse_show_create_table で構造を把握し、ソートキーとパーティションのカラムで絞り込み、SQL 内で集計し（count()、sum()、uniq()、quantile(0.95)(x)、toStartOfDay(ts)）、必ず LIMIT で終えます。大きなテーブルをスキャンしそうなクエリの前には EXPLAIN や EXPLAIN ESTIMATE を実行できます。クエリは FORMAT 句も末尾のセミコロンもない 1 文で、database を指定するとデータベース名のないテーブル名の既定データベースになります。

データ形式: JSON 形式では meta（カラム名と型）、data（行）、rows（行数）、statistics（経過秒数、読み取った行数とバイト数）が返ります。clickhouse_query は JSONCompact（行を配列で返す小さい形式）、CSVWithNames、TabSeparatedWithNames でも返せます。64 ビット整数（UInt64、Int64）は文字列で届くので、"12345678901" は数値です。DateTime の値は、カラム型が別のタイムゾーンを指定していない限り、clickhouse_server_info が示すサーバーのタイムゾーンでの YYYY-MM-DD hh:mm:ss です。formatReadableSize のサイズは 2 進単位（KiB、MiB、GiB）です。

ページングと制限: ページングはなく、行数の上限もあなたの LIMIT とコネクタの応答サイズ上限だけです。結果全体が 1 回の応答で返るため、生の行を取得するより集計してください。clickhouse_search_columns は最大 500 件を返します。clickhouse_recent_queries は minutes（既定 60）以内の直近 100 件のクエリを返します。clickhouse_running_queries は応答したノードだけを示し、ClickHouse Cloud ではサービスのレプリカ 1 つ分です。アイドル状態の Cloud サービスは最初のクエリで起動し、最大 1 分ほどかかることがあります。

よくあるエラー: 本文には Code: <n>. DB::Exception: ... が入ります。コード 164（READONLY）は、文が書き込みや設定の変更を行おうとしたことを示します。497（ACCESS_DENIED、HTTP 403）は GRANT の不足、または ClickHouse Cloud で IP access list がこのサーバーを許可していないことを示します。60（UNKNOWN_TABLE）と 81（UNKNOWN_DATABASE）は名前の誤り、62（SYNTAX_ERROR）は SQL の誤り、159 または 241 はタイムアウトかメモリ上限です。クエリを絞り込んでください。401 または 516（AUTHENTICATION_FAILED）はユーザー名かパスワードの誤りです。アドレスで何も応答しない場合は、たいていポートの誤りか、CLICKHOUSE_URL にパスが含まれています。

このコネクタはデータの挿入、更新、削除を行わず、テーブルの作成や変更もしません。ClickHouse Cloud サービスの管理（起動、停止、スケーリング、バックアップ、コスト）も行いません。それには別の ClickHouse Cloud コネクタをインストールしてください。

ステップ 2 — アダプターをインストール

curl -fsSL https://raw.githubusercontent.com/HelpCode-ai/anythingmcp/main/docker-compose.quickstart.yml -o docker-compose.yml
printf 'JWT_SECRET=%s\nENCRYPTION_KEY=%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env
docker compose up -d

ステップ 3 — Cursor にコネクタを追加

サーバーURL: AnythingMCP で MCP Servers を開き、このコネクタがあるサーバーを選んで URL（https://cloud.anythingmcp.com/mcp/…）をコピーします。このガイドで YOUR_SERVER_ID と表示されている箇所に使ってください。

Cursor は ~/.cursor/mcp.json から MCP サーバーを読み込みます。次のエントリを追加してください:

{
  "mcpServers": {
    "anythingmcp": {
      "url": "https://cloud.anythingmcp.com/mcp/YOUR_SERVER_ID",
      "headers": { "X-API-Key": "YOUR_MCP_API_KEY" }
    }
  }
}

1. AnythingMCP の MCP Servers → 対象のサーバー → API keys で MCP API キーを作成し、YOUR_MCP_API_KEY と置き換えます。
2. ファイルを保存し、Cursor を再起動します。
3. Cursor → Settings → MCP を開き、anythingmcp が一覧にあり接続済みであることを確認します。
4. チャットを始めましょう。エージェントが ClickHouse のツールを呼び出せるようになりました。

利用可能なツール

プロンプトの例

• 「どんなデータベースとテーブルがあり、どのテーブルがいちばんディスクを使っていますか？」
• 「直近 30 日間、analytics.events のイベントは 1 日あたり何件でしたか？」
• 「customer_id のようなカラムはどこにありますか？ すべてのデータベースを検索してください。」
• 「直近 1 時間に失敗したクエリを、エラーコード付きで見せてください。」
• 「今月の売上上位 10 か国はどこですか？ クエリを軽く保つため、先にソートキーを確認してください。」

FAQ

Cursor の無料プランでカスタム MCP サーバーは使えますか? はい。MCP は Hobby、Pro、Business の各プランで利用できます。

次のステップ

• コネクタのランディング
• Claude に接続
• ChatGPT に接続
• Gemini に接続
• Meta Muse に接続
• Microsoft Copilot に接続