ClickHouse

公式

ClickHouseデータベースサーバーにクエリを実行します。

GitHub
899

ClickHouse MCPで何ができますか？

  • Run SQL queries — run_query を使用して、ClickHouse クラスター上で任意の SQL クエリを実行するよう依頼します。params を使用してオプションの名前付きパラメータを指定できます。
  • List databases — list_databases を使用して、ClickHouse クラスターで利用可能なすべてのデータベースを検出します。
  • Browse tables with filters — list_tables を使用してデータベース内のテーブルを探索し、like/not_like パターンと、page_token および page_size によるページネーションを適用します。
  • Inspect query schemas — 実行前に出力列や推定読み取り量を確認するために、run_query を通じて DESCRIBE (<query>) または EXPLAIN ESTIMATE <query> を依頼します。
  • Query embedded chDB data — ETL なしでファイル、URL、またはデータベースをクエリするために、run_chdb_select_query を使用して chDB の組み込みエンジンに対して直接 SQL を実行します。

ドキュメント

ClickHouse MCP サーバー

PyPI - Version

ClickHouse 用の MCP サーバーです。

mcp-clickhouse MCP server

このサーバーは MCP 2026-07-28 を実装し、2024-11-05 から 2025-11-25 までのレガシーな initialize ハンドシェイクをサポートしています。モダンなクライアントはセッションレスリクエストと server/discover を使用します。既存のクライアントはレガシープロトコルのネゴシエーションを継続できます。

[!NOTE] MCP-Protocol-Version を含まない HTTP リクエストはレガシーハンドリング経由でルーティングされるため、2025-06-18 より前のクライアントも接続を継続できます。MCP 2026-07-28 は、これらのクライアントをサポートするサーバーでこの動作を許可しています。モダンなクライアントはすべての POST リクエストでヘッダーを送信する必要があります。

機能

ClickHouse ツール

ClickHouse ツールのレスポンスは JSON エンコードされた文字列です。[-9007199254740991, 9007199254740991] の範囲外の整数は、JavaScript クライアントで正確な値を保持するために 10 進数の文字列として返されます。これはクエリ行と整数のテーブルメタデータに適用されます。安全な範囲内の整数とブール値は JSON 型を維持します。

  • run_query

    • ClickHouse クラスターで SQL クエリを実行します。
    • 入力: query (文字列): 実行する SQL クエリ。
    • オプション入力: params (オブジェクト): ClickHouse の {name:Type} プレースホルダー用の名前付き値。クエリパラメータ を参照してください。
    • クエリはデフォルトで読み取り専用モードで実行されます (CLICKHOUSE_ALLOW_WRITE_ACCESS=false) が、必要に応じて書き込みを明示的に有効にできます。
    • DESCRIBE (<query>) と EXPLAIN ESTIMATE <query> もここで実行され、クエリの結果スキーマや推定読み取り量を検査するオプションの方法です。実行前のクエリ確認 を参照してください。

  • list_databases

    • ClickHouse クラスター上のすべてのデータベースを一覧表示します。

  • list_tables

    • データベース内のテーブルをページネーション付きで一覧表示します。
    • 必須入力: database (文字列)。
    • オプション入力:
      • like / not_like (文字列): テーブル名に LIKE または NOT LIKE フィルターを適用します。
      • page_token (文字列): 前回の呼び出しで返された単回使用トークン。最大 1 時間保持されます。
      • page_size (int、デフォルト 50): 1 ページあたりに返されるテーブル数。0 より大きくなければなりません。
      • include_detailed_columns (bool、デフォルト true): false の場合、完全な create_table_query を維持しながら、軽量なレスポンスのために列メタデータを省略します。
    • レスポンス形式:
      • tables: 現在のページのテーブルオブジェクトの配列。
      • next_page_token: 有効期限前にこの単回使用値を渡すと次のページを取得できます。テーブルがもうない場合は null になります。
      • total_tables: 指定されたフィルターに一致するテーブルの総数。

Agents スキーマの検出

サーバーの指示では、分析 SQL を書く前に、list_databases が AGENTS データベースを明らかにした場合、Agents Schema の正規の AGENTS.ROOT から run_query を読むことを推奨しています。これはエージェントへのガイダンスです。メタデータは自動的に取得されず、ツールの結果は変更されず、既存の ClickHouse 権限が引き続き適用されます。AGENTS.ROOT が存在しないかアクセスできない場合でも、通常の検出とクエリは引き続き利用できます。

クエリパラメータ

SQL とは別に、オプションの params オブジェクトを通じて値を渡します:

{
  "query": "SELECT {id:UInt32} AS id, {name:String} AS name",
  "params": {"id": 13, "name": "O'Reilly"}
}

ClickHouse の {name:Type} プレースホルダーを引用符なしで使用します。開始中括弧、名前、コロンを隣接させてください。例: {id:UInt32}。コロン後のスペースと型内のスペースはサポートされています。例: {id: UInt32} と {amount:Decimal(18, 4)}。サポートされているドライバーバージョン間の互換性のため、名前は文字またはアンダースコアで始め、文字、数字、アンダースコアのみを使用してください。 Python スタイルの %s または %(name)s フォーマットと、ドライバーの $name$ 生バイナリパラメータはサポートされていません。query のみの呼び出しは引き続き機能します。params を省略するか、null を渡すか、空のオブジェクトを渡すと、クエリはバインドされません。

パラメータ値は、宣言された ClickHouse 型と一致する場合、JSON 文字列、数値、ブール値、null、または配列にできます:

  • null 型で Nullable(...) を使用します。
  • JavaScript の安全な範囲外の正確な整数は 10 進数の文字列として渡します。例: "18446744073709551615" と {id:UInt64}。日付、タイムスタンプ、正確な小数も、対応する ClickHouse 型の文字列として渡せます。
  • ベクトルを 1 つの配列としてバインドします。例: {vector:Array(Float32)} と "params": {"vector": [0.25, 0.5, 0.75]}。
  • 配列内の null はインストールされているドライバーに依存します。clickhouse-connect 1.8.0 では機能しますが、サポートされている最小バージョン 1.0.0 では失敗します。
  • JSON リストとオブジェクトは ClickHouse の Tuple および Map 型にバインドできません。

欠落している値や互換性のない型はクエリエラーを返します。空でない params の場合、多数の未終了の {name: プレースホルダー開始を含むクエリは拒否されます。コメントや文字列リテラル内のプレースホルダー風テキストも含まれます。パラメータ化されたクエリは、他のクエリと同じ書き込み保護、タイムアウト、キャンセル、JSON 結果エンコーディングを使用します。

パラメータ値は MCP サーバーの通常の SQL ログメッセージには含まれませんが、MCP ツールの引数には残り、バックエンドエラーに表示される可能性があります。ClickHouse 26.3.20.7 は、system.query_log、system.processes、system.text_log でクエリテキストに値を代入します。パラメータバインディングはプライバシー機能ではなく、ツール呼び出しで送信されるベクトル値の数を減らすものでもありません。

実行前のクエリ確認

run_query は DESCRIBE と EXPLAIN ESTIMATE も実行します。どちらもオプションのチェックです。クエリの出力列と型が必要な場合は DESCRIBE を、高コストになる可能性のある SELECT の前に EXPLAIN ESTIMATE を使用してください。

DESCRIBE (<query>) は結果スキーマを検査し、DESCRIBE TABLE と同じ出力列メタデータを返します:

DESCRIBE (SELECT user, sum(amt) FROM events WHERE ts > now() - INTERVAL 30 DAY GROUP BY user)

user      String
sum(amt)  Decimal(38, 2)

ClickHouse は応答するためにクエリを分析する必要があるため、分析エラーはここで ClickHouse 自身のメッセージとともに表示され、実行途中で発生することはありません:

DESCRIBE (SELECT usr FROM events)  -> Code: 47. Unknown expression identifier `usr` ... Maybe you meant: ['user']
DESCRIBE (SELECT * FROM nosuch)    -> Code: 60. Unknown table expression identifier 'nosuch'

正常に記述できるクエリでも、実行時にメモリ制限やリモートサーバーエラーで失敗する可能性があり、コストについては何も示しません。

EXPLAIN ESTIMATE <query> は、クエリが読み取るパーツ、行、マークをテーブルごとに 1 行で返します。これがプライマリキールックアップとフルスキャンを区別するものです:

EXPLAIN ESTIMATE SELECT count() FROM events WHERE id = 42

database  table   parts  rows   marks
default   events  1      8192   1

これらは MergeTree ファミリーテーブルからの推定読み取り量で、プライマリキーとパーティションプルーニング後です。実行時間や結果サイズではなく、他のテーブルエンジンは対象外です。

どちらのステートメントもクエリ本体を実行しませんが、分析は常に無料とは限りません: DESCRIBE (SELECT (SELECT sleep(1))) は分析中にスカラーサブクエリを実行します。どちらも読み取り専用で、デフォルトの CLICKHOUSE_ALLOW_WRITE_ACCESS=false で動作します。ClickHouse のドキュメントの EXPLAIN ESTIMATE と DESCRIBE を参照してください。

chDB ツール

  • run_chdb_select_query
    • chDB の組み込み ClickHouse エンジンを使用して SQL クエリを実行します。
    • 入力: query (文字列): 実行する SQL クエリ。
    • [-9007199254740991, 9007199254740991] の範囲外の整数は 10 進数の文字列として返されます。
    • ETL プロセスなしで、さまざまなソース (ファイル、URL、データベース) から直接データをクエリします。
    • オプションの chdb エクストラが必要です: pip install 'mcp-clickhouse[chdb]'

ヘルスチェックエンドポイント

HTTP または SSE トランスポートで実行する場合、ヘルスチェックエンドポイントが /health で利用できます。このエンドポイントは:

  • サーバーが正常で ClickHouse に接続できる場合は 200 OK (ボディ: OK) を返します
  • サーバーが ClickHouse に接続できない場合は、一般的なエラーメッセージとともに 503 Service Unavailable を返します
  • ClickHouse プローブが 2 秒以内に完了しない場合は 503 を返します。同時リクエストは 1 つの進行中のプローブを共有します
  • 完了したプローブ結果を 1 秒間再利用するため、連続して到着するプローブがそれぞれ ClickHouse に接続することはありません。したがって、障害または回復は最大 1 秒遅れて報告される可能性があります

エンドポイントへの GET および HEAD リクエストは意図的に認証なしで、Host および Origin 検証の対象外です。これにより、オーケストレータープローブ (Kubernetes の liveness/readiness、ロードバランサーなど) が追加設定なしでランタイム割り当てのポッド IP またはターゲット IP を使用できます。/health は予約されており、MCP トランスポートパスとして使用できません。レスポンスボディは、バックエンドのバージョン文字列やエラー詳細を漏らさないように意図的に最小限にしています。デバッグの失敗はサーバーログで確認してください。

例:

curl http://localhost:8000/health
# Response: OK

セキュリティ

HTTP/SSE トランスポートの認証

HTTP または SSE トランスポートを使用する場合、認証はデフォルトで必須です。stdio トランスポート (デフォルト) は標準入出力のみで通信するため、認証は不要です。

3 つの認証モードがサポートされています。1 つ選択してください:

モード使用タイミング環境変数
静的ベアラートークンシンプルなデプロイ、内部サービスCLICKHOUSE_MCP_AUTH_TOKEN
OAuth / OIDC (FastMCP 経由)Azure Entra、Google、GitHub、WorkOS などFASTMCP_SERVER_AUTH=<provider-class-path> (+ プロバイダー固有の FASTMCP_SERVER_AUTH_* 変数)
無効ローカル開発のみCLICKHOUSE_MCP_AUTH_DISABLED=true

HTTP/SSE トランスポートでこれらのいずれも設定されていない場合、起動は失敗します。

認証の設定

  1. セキュアなトークンを生成します (任意のランダム文字列で可):

    # Using uuidgen (macOS/Linux)
uuidgen

# Using openssl
openssl rand -hex 32

  2. トークンでサーバーを設定します:

    export CLICKHOUSE_MCP_AUTH_TOKEN="your-generated-token"

  3. MCP クライアントがリクエストにトークンを含めるように設定します:

    HTTP/SSE トランスポートを使用する Claude Desktop の場合:

    {
  "mcpServers": {
    "mcp-clickhouse": {
      "url": "http://127.0.0.1:8000",
      "headers": {
        "Authorization": "Bearer your-generated-token"
      }
    }
  }
}

    注: /health エンドポイントは意図的に認証なしです (上記の ヘルスチェックエンドポイント を参照)。ベアラートークン認証が実際に未認証リクエストを拒否していることを確認するには、MCP Inspector などで MCP エンドポイント自体にアクセスするか、/mcp に Authorization ヘッダーありとなしで JSON-RPC リクエストを POST し、未認証の呼び出しが 401 を返すことを確認してください。

FastMCP 経由の OAuth / OIDC

ID プロバイダー (Azure Entra、Google、GitHub、WorkOS など) を使用した本番デプロイでは、静的トークンを使用する代わりに、FastMCP の組み込み認証プロバイダー に認証を委任します。FASTMCP_SERVER_AUTH を FastMCP 認証プロバイダーの完全なクラスパスに設定し、プロバイダー固有の FASTMCP_SERVER_AUTH_* 変数を設定し、CLICKHOUSE_MCP_AUTH_TOKEN は未設定のままにします。

例 (Azure Entra):

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"
export FASTMCP_SERVER_AUTH_AZURE_REQUIRED_SCOPES="read access_as_user"

mcp-clickhouse は、FastMCP 4.0.0 の組み込みプロバイダーに対して、これらの FastMCP 2.14.7 環境変数プレフィックスを保持します:

プロバイダークラスパスプロバイダー変数プレフィックス
fastmcp.server.auth.providers.auth0.Auth0ProviderFASTMCP_SERVER_AUTH_AUTH0_
fastmcp.server.auth.providers.aws.AWSCognitoProviderFASTMCP_SERVER_AUTH_AWS_COGNITO_
fastmcp.server.auth.providers.azure.AzureProviderFASTMCP_SERVER_AUTH_AZURE_
fastmcp.server.auth.providers.descope.DescopeProviderFASTMCP_SERVER_AUTH_DESCOPEPROVIDER_
fastmcp.server.auth.providers.discord.DiscordProviderFASTMCP_SERVER_AUTH_DISCORD_
fastmcp.server.auth.providers.github.GitHubProviderFASTMCP_SERVER_AUTH_GITHUB_
fastmcp.server.auth.providers.google.GoogleProviderFASTMCP_SERVER_AUTH_GOOGLE_
fastmcp.server.auth.providers.introspection.IntrospectionTokenVerifierFASTMCP_SERVER_AUTH_INTROSPECTION_
fastmcp.server.auth.providers.jwt.JWTVerifierFASTMCP_SERVER_AUTH_JWT_
fastmcp.server.auth.providers.oci.OCIProviderFASTMCP_SERVER_AUTH_OCI_
fastmcp.server.auth.providers.scalekit.ScalekitProviderFASTMCP_SERVER_AUTH_SCALEKITPROVIDER_
fastmcp.server.auth.providers.supabase.SupabaseProviderFASTMCP_SERVER_AUTH_SUPABASE_
fastmcp.server.auth.providers.workos.WorkOSProviderFASTMCP_SERVER_AUTH_WORKOS_
fastmcp.server.auth.providers.workos.AuthKitProviderFASTMCP_SERVER_AUTH_AUTHKITPROVIDER_

プレフィックスに大文字のプロバイダーフィールド名を追加します。各プロバイダーの設定要件については、FastMCP ドキュメント を参照してください。 プロセス環境に直接設定された認証値は、大文字小文字を区別せずに優先されます。 デフォルトの.env読み込みは、インストールされたmcp_clickhouseパッケージディレクトリから開始され、 最初にシンボリックリンクを解決し、ファイルシステムのルートまで上方向に移動します。最初に見つかった .envを読み込み、存在しない場合は何も読み込みません。サーバーの起動方法に関係なく、 作業ディレクトリを読み取ることはありません。ソースチェックアウトでは通常、 リポジトリルートの.envが見つかります。そのファイルはFASTMCP_SERVER_AUTHとその プロバイダーフィールドも提供する場合があります。その値は、明示的または互換性のある認証 ファイルよりも優先されます。 FastMCP 2互換性のため、mcp-clickhouseは作業ディレクトリ内の.envから欠落しているプロバイダーフィールドを読み取りますが、 その互換性フォールバックはFASTMCP_SERVER_AUTHを選択できません。 プロセス設定のFASTMCP_ENV_FILEはその互換性フォールバックを置き換え、 セレクターフィールドとプロバイダーフィールドの両方を提供できます。起動前に設定してください。 mcp-clickhouse互換性ローダーは、そのファイルからFASTMCP_SERVER_AUTHと FASTMCP_SERVER_AUTH_*のみを読み取るため、CLICKHOUSE_*設定を注入できません。 FastMCP 4は、独自のより広範な設定に同じファイルを使用する場合があります。カスタムプロバイダーは 環境から派生したコンストラクター引数を受け取らず、引数なしの構築をサポートする必要があります。

検出されたファイルと作業ディレクトリの.envファイルの両方を、信頼できる認証 設定として扱います。パッケージディレクトリからファイルシステムのルートまでの任意のディレクトリに .envを作成または書き込みできる人は誰でも、検出されるファイルを制御し、 プロバイダーを選択し、そのフィールドを設定できます。作業ディレクトリのファイルを書き込める人は、 プロセスと検出された設定に存在しないすべてのプロバイダーフィールドを制御できます。これには、 署名キー、発行者とエンドポイント、クライアントシークレットが含まれます。オペレーター所有のファイルを 指すプロセス設定のFASTMCP_ENV_FILEは、作業ディレクトリのフォールバックを無効にします。

FastMCP 4は、デフォルトのOAuthプロキシクライアントストアを変更しました。FastMCP 2の デフォルトのOAuthプロキシストレージに依存していたデプロイメントは、クライアントを再登録して 再認証する必要があります。互換性のあるカスタムストレージ、静的ベアラートークン、JWT検証は影響を受けません。

開発モード（認証の無効化）

ローカル開発およびテストのみを目的として、以下を設定することで認証を無効にできます：

export CLICKHOUSE_MCP_AUTH_DISABLED=true
export CLICKHOUSE_MCP_ALLOWED_HOSTS=127.0.0.1:8000,localhost:8000

警告： これはローカル開発専用です。サーバーがネットワークに公開されている場合は、認証を無効にしないでください。

設定

このMCPサーバーはClickHouseとchDBの両方をサポートしています。ニーズに応じて、いずれかまたは両方を有効にできます。 Python 3.10から3.14がサポートされています。ローカル起動にはPython 3.12が推奨されます。

  1. Claude Desktopの設定ファイルを開きます。場所は次のとおりです：

    • macOSの場合：~/Library/Application Support/Claude/claude_desktop_config.json
    • Windowsの場合：%APPDATA%/Claude/claude_desktop_config.json

  2. 以下を追加します：

{
  "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_ROLE": "<clickhouse-role>",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30"
      }
    }
  }
}

環境変数を更新して、ご自身のClickHouseサービスを指すようにします。

または、ClickHouse SQL Playgroundで試してみたい場合は、次の設定を使用できます：

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.12",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
        "CLICKHOUSE_PORT": "8443",
        "CLICKHOUSE_USER": "demo",
        "CLICKHOUSE_PASSWORD": "",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30"
      }
    }
  }
}

chDB（組み込みClickHouseエンジン）の場合は、次の設定を追加します：

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse[chdb]",
        "--python",
        "3.12",
        "mcp-clickhouse"
      ],
      "env": {
        "CHDB_ENABLED": "true",
        "CLICKHOUSE_ENABLED": "false",
        "CHDB_DATA_PATH": "/path/to/chdb/data"
      }
    }
  }
}

ClickHouseとchDBの両方を同時に有効にすることもできます：

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse[chdb]",
        "--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_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30",
        "CHDB_ENABLED": "true",
        "CHDB_DATA_PATH": "/path/to/chdb/data"
      }
    }
  }
}

  1. uvのコマンドエントリを見つけ、uv実行可能ファイルの絶対パスに置き換えます。これにより、サーバー起動時に正しいバージョンのuvが使用されます。Macでは、which uvを使用してこのパスを見つけることができます。

  2. Claude Desktopを再起動して変更を適用します。

オプションの書き込みアクセス

デフォルトでは、このMCPは読み取り専用クエリを強制するため、探索中に誤った変更が発生することはありません。DDLまたはINSERTステートメントを許可するには、CLICKHOUSE_ALLOW_WRITE_ACCESS環境変数をtrueに設定します。ClickHouseインスタンス自体が書き込みを許可しない場合、サーバーは読み取り専用モードを引き続き強制します。

読み取り専用モードでも、ClickHouseユーザーは自分のクエリをキャンセルできます。これには、同じユーザーを使用する他の接続からのクエリも含まれます。読み取り専用モードでも専用のClickHouseユーザーを使用してください。互いのクエリをキャンセルしてはならないワークロードには、別々のClickHouseユーザーを使用してください。

破壊的操作の保護

書き込みアクセスが有効な場合（CLICKHOUSE_ALLOW_WRITE_ACCESS=true）でも、破壊的操作には安全性のための追加のオプトインフラグが必要です。このチェックは、任意のDROPステートメント（ALTER TABLE ... DROP PARTITION / DROP PART / DROP COLUMN句を含む）、任意のTRUNCATE、DELETEおよびUPDATE（軽量ステートメントとALTER TABLE ... DELETE / ALTER TABLE ... UPDATEミューテーションの両方）、REPLACE TABLE、CREATE OR REPLACE、ALTER TABLE ... REPLACE PARTITION、ALTER TABLE ... CLEAR COLUMN / CLEAR INDEX / CLEAR PROJECTION、およびDETACH ... PERMANENTLYを対象とします。文字列リテラル、引用符付き識別子、SQLコメント、{name:Type}パラメーター名内のキーワードは無視されるため、チェックをトリガーしたり、ステートメントをチェックから隠したりしません。

このチェックはMCPサーバーで実行され、事故に対するベストエフォートのガードです。セキュリティ境界ではありません。セキュリティ境界はClickHouseユーザーの権限です。読み取り専用モード（デフォルト）は、readonly=1を介してサーバー側で強制されます。破壊的操作ゲートはサーバー側で強制されません。

書き込みモードの場合は、MCPサーバーに必要な権限のみを持つ専用のClickHouseユーザーを指定します：

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

これらの権限の範囲外の権限を必要とするデータ変更操作は、MCPフラグに関係なく、ACCESS_DENIEDでサーバー側で失敗します。サーバー設定のmax_table_size_to_dropとmax_partition_size_to_dropは、設定制約で固定されている場合、影響範囲を制限することもできます。

破壊的操作を有効にするには、両方のフラグを設定します：

"env": {
  "CLICKHOUSE_ALLOW_WRITE_ACCESS": "true",
  "CLICKHOUSE_ALLOW_DROP": "true"
}

この2段階のアプローチにより、誤った削除が困難になります：

  • 書き込み操作（INSERT、CREATE、ALTER ADD COLUMN）にはCLICKHOUSE_ALLOW_WRITE_ACCESS=trueが必要です
  • 破壊的操作（DROP、TRUNCATE、DELETE、UPDATE、および上記のリストの残り）には追加でCLICKHOUSE_ALLOW_DROP=trueが必要です

uvなしでの実行（システムPythonの使用）

uvの代わりにシステムのPythonインストールを使用したい場合は、PyPIからパッケージをインストールして直接実行できます：

  1. pipを使用してパッケージをインストールします：

    python3 -m pip install mcp-clickhouse

    chDBサポートもインストールするには：

    python3 -m pip install 'mcp-clickhouse[chdb]'

    最新バージョンにアップグレードするには：

    python3 -m pip install --upgrade mcp-clickhouse

  2. Claude Desktopの設定を更新して、Pythonを直接使用します：

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "python3",
      "args": [
        "-m",
        "mcp_clickhouse.main"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_PORT": "<clickhouse-port>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30"
      }
    }
  }
}

または、インストールされたスクリプトを直接使用することもできます：

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "mcp-clickhouse",
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_PORT": "<clickhouse-port>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30"
      }
    }
  }
}

注：Python実行可能ファイルまたはmcp-clickhouseスクリプトがシステムのPATHにない場合は、フルパスを使用してください。パスは次を使用して見つけることができます：

  • Python実行可能ファイルの場合はwhich python3
  • インストールされたスクリプトの場合はwhich mcp-clickhouse

カスタムミドルウェア

ソースコードを変更せずに、MCPサーバーにカスタムミドルウェアを追加できます。FastMCPは、MCPプロトコルメッセージ（ツール呼び出し、リソース読み取り、プロンプトなど）をインターセプトして処理できるミドルウェアシステムを提供します。

使用方法

  1. Middlewareを拡張するミドルウェアクラスとsetup_middleware(mcp)関数を持つPythonモジュールを作成します：
# my_middleware.py
import logging
from fastmcp.server.middleware import Middleware, MiddlewareContext, CallNext

logger = logging.getLogger("my-middleware")

class LoggingMiddleware(Middleware):
    """Log all tool calls."""
    
    async def on_call_tool(self, context: MiddlewareContext, call_next: CallNext):
        tool_name = context.message.name if hasattr(context.message, 'name') else 'unknown'
        logger.info(f"Calling tool: {tool_name}")
        result = await call_next(context)
        logger.info(f"Tool {tool_name} completed")
        return result

def setup_middleware(mcp):
    """Register middleware with the MCP server."""
    mcp.add_middleware(LoggingMiddleware())
  1. MCP_MIDDLEWARE_MODULE環境変数をモジュール名に設定します（.py拡張子なし）：
{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": ["run", "--with", "mcp-clickhouse", "--python", "3.12", "mcp-clickhouse"],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "MCP_MIDDLEWARE_MODULE": "my_middleware"
      }
    }
  }
}
  1. ミドルウェアモジュールがPythonのインポートパスにあることを確認します（例：MCPサーバーが実行されるディレクトリ、またはパッケージとしてインストール）。

ミドルウェアの例

example_middleware.pyに一般的なパターンを示すミドルウェアモジュールの例が提供されています：

  • すべてのMCPリクエストのロギング
  • ツール呼び出しの具体的なロギング
  • リクエスト処理時間の測定

例を使用するには：

"env": {
  "MCP_MIDDLEWARE_MODULE": "example_middleware"
}

ミドルウェア機能

Middleware基本クラスは、さまざまなMCP操作のフックを提供します：

  • on_message(context, call_next) - すべてのメッセージに対して呼び出されます
  • on_request(context, call_next) - すべてのリクエストに対して呼び出されます
  • on_notification(context, call_next) - すべての通知に対して呼び出されます
  • on_call_tool(context, call_next) - ツールが実行されるときに呼び出されます
  • on_read_resource(context, call_next) - リソースが読み取られるときに呼び出されます
  • on_get_prompt(context, call_next) - プロンプトが取得されるときに呼び出されます
  • on_list_tools(context, call_next) - ツールの一覧表示時に呼び出されます
  • on_list_resources(context, call_next) - リソースの一覧表示時に呼び出されます
  • on_list_resource_templates(context, call_next) - リソーステンプレートの一覧表示時に呼び出されます
  • on_list_prompts(context, call_next) - プロンプトの一覧表示時に呼び出されます

各フックは、メッセージとメタデータを含むMiddlewareContextオブジェクトと、パイプラインを続行するためのcall_next関数を受け取ります。

コンテキスト状態による動的クライアント設定

ミドルウェアは、CLIENT_CONFIG_OVERRIDES_KEYコンテキスト状態キーを使用して、リクエストごとにClickHouseクライアント設定をオーバーライドできます。サーバーはこれらのオーバーライドを環境変数の基本設定とマージします。

from fastmcp.server.dependencies import get_context
from fastmcp.server.middleware import CallNext, Middleware, MiddlewareContext
from mcp_clickhouse.mcp_server import CLIENT_CONFIG_OVERRIDES_KEY


class ClientConfigMiddleware(Middleware):
    async def on_call_tool(self, context: MiddlewareContext, call_next: CallNext):
        ctx = get_context()
        await ctx.set_state(
            CLIENT_CONFIG_OVERRIDES_KEY,
            {
                "connect_timeout": 60,
                "send_receive_timeout": 120,
            },
            serializable=False,
        )
        return await call_next(context)

これにより、動的なタイムアウト調整、テナント固有のルーティング、ユーザーごとの接続設定などの高度なユースケースが可能になります。

状態値は辞書である必要があります。ネストされたsettingsとgeneric_args値は マッピングである必要があり、基本設定とマージされます。無効な値は、ClickHouseクライアントが 作成される前にツール呼び出しを失敗させます。CLICKHOUSE_ROLEは、オーバーライドが明示的に settings.roleを提供しない限りアクティブのままです。トップレベルのroleとch_roleキー、および generic_argsの下の同じキーは拒否されます。

verify、ca_cert、client_cert、client_cert_key、tls_mode、server_host_name、 およびpool_mgrは、トップレベルのオーバーライドとしてのみ設定します。generic_argsの下にネストすることはできません。 カスタムpool_mgrは、管理されたCAまたはクライアント証明書設定と組み合わせることはできません。DSNクエリ パラメータはこれらのキーを設定できず、DSNはchdbバックエンドを選択できません。明示的な トップレベルのhost、port、username、password、database、およびsecureオーバーライドを使用して 接続を変更します。転送されたDSNは、設定済みの基本接続フィールドを置き換えたり、TLSを選択したりしません。 空のフィールドを埋め、query_limitなどのサポートされているクエリパラメータを提供できます。 secureとverifyのオーバーライドは、ブール値または文字列trueとfalseを受け入れます。 verifyはproxyも受け入れます。これはtls_modeが未設定の場合に tls_mode: proxyとして動作し、したがって環境パスワードを使用したBasic認証を使用します。secureのオーバーライドは、一致するhttpsまたはhttpインターフェースを選択し、 ポートは変更しません。明示的なinterfaceオーバーライドはhttpまたはhttpsである必要があり、secureと一致する必要があります。 オーバーライドのマージ後、デフォルトおよびmutualクライアント証明書モードはパスワードを省略します。 proxyおよびstrictモードは、オーバーライドが独自の資格情報を提供しない限り、 環境パスワードを使用したBasic認証を使用します。

これらのオーバーライドは信頼できるミドルウェア入力として扱います。ミドルウェアは、設定する前に リクエストから派生した値を認証および承認する必要があります。serializable=Falseを使用して、FastMCPが 値をリクエストローカル状態に保持するようにします。デフォルトのserializable=Trueはセッション状態を保存し、 サーバーによって拒否されます。サーバーは、ブロッキングデータベース作業をディスパッチする前に値をスナップショットします。 テナントデータをセッションスコープのContext状態に保存しないでください。拒否されたセッションスコープの オーバーライドはレガシーMCPセッションにアタッチされたままで、クライアントが再接続するまでそのセッションの後続のツール呼び出しが 失敗します。リクエストごとのClickHouseロールは接続設定であり、 テナント認証境界ではありません。ClickHouseユーザー、ロール、および権限でテナント分離を強制します。

開発

  1. test-servicesディレクトリでdocker compose up -dを実行してClickHouseクラスターを起動します。

  2. リポジトリのルートにある.envファイルに次の変数を追加します。

注：このコンテキストでのdefaultユーザーの使用は、ローカル開発目的のみを意図しています。

CLICKHOUSE_HOST=localhost
CLICKHOUSE_PORT=8123
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse

  1. uv sync を実行して依存関係をインストールします。uv をインストールするには、こちらの手順に従ってください。その後、source .venv/bin/activate を実行します。

  2. MCP Inspector で簡単にテストするには、uv run fastmcp dev inspector mcp_clickhouse/mcp_server.py:mcp を実行して MCP サーバーを起動します。

  3. HTTP トランスポートとヘルスチェックエンドポイントでテストするには:

    # For development, disable authentication
CLICKHOUSE_MCP_SERVER_TRANSPORT=http CLICKHOUSE_MCP_AUTH_DISABLED=true CLICKHOUSE_MCP_ALLOWED_HOSTS=127.0.0.1:8000,localhost:8000 python -m mcp_clickhouse.main

# Or with authentication (generate a token first)
CLICKHOUSE_MCP_SERVER_TRANSPORT=http CLICKHOUSE_MCP_AUTH_TOKEN="your-token" python -m mcp_clickhouse.main

# Then in another terminal:
curl http://localhost:8000/health

コードレイアウト

このパッケージはフラットなモジュールレイアウトを使用しています。mcp_server.py から始めてサーバーの組み立てと登録を確認し、実装をその所有モジュールへと追っていきます。

モジュール責務
mcp_server.py、main.py起動時の組み立て、ツールとプロンプトの登録、シャットダウン調整、CLI 起動
clients.pyリクエスト設定、キャッシュされた ClickHouse 接続、クライアントリース
queries.pyクエリ実行、キャンセル、破壊的操作ガード
metadata.pyデータベースとテーブルの検出、メタデータモデル、ページネーション
chdb_backend.py、chdb_prompt.pyオプションの chDB 初期化、クエリ実行、プロンプトコンテンツ
health.py、executors.pyヘルスプローブとキャッシュ、サーバー操作で使用されるワーカープール
auth.py、transport.py、http_security.pyDotenv 読み込み、認証、HTTP/SSE アプリ構築、Host/Origin 検証
mcp_env.py、serialization.py環境設定と JSON 結果エンコーディング
mcp_middleware_hook.py、skills_advisor.pyカスタムミドルウェアの読み込みとサーバー指示

各サーバーアセンブリは、ワーカープール、クライアントキャッシュ、アクティブなクエリ、ページネーションキャッシュ、ヘルス状態、chDB バックエンドを所有します。ワーカーとクライアントのクリーンアップはプロセス終了時に実行されます。パッケージのインポートは、抽出されたモジュールを最初にインポートするときを含め、デフォルトサーバーを初期化します。

テストでは、コードが依存関係を読み取る場所のモジュールまたはオーナーインスタンスをパッチします。たとえば、クライアント作成には mcp_clickhouse.clients.clickhouse_connect.get_client をパッチします。mcp_server.py の互換性インポートは、実装が使用するものとは別のバインディングにすることができます。

環境変数

設定は独立したグループに分かれています。これらを混同すると、デバッグが難しい接続障害の一般的な原因になります:

グループ変数制御対象
ClickHouse データベース接続CLICKHOUSE_HOST、CLICKHOUSE_PORT、CLICKHOUSE_SECURE、CLICKHOUSE_VERIFY、証明書変数この MCP サーバーが HTTP インターフェース経由で ClickHouse クラスターに接続する方法
MCP サーバー / トランスポートCLICKHOUSE_MCP_*、FASTMCP_SERVER_AUTH、FASTMCP_SERVER_AUTH_*、FASTMCP_ENV_FILEMCP トランスポート、認証、クエリツール実行制限
ミドルウェア / chDBMCP_MIDDLEWARE_MODULE、CHDB_*オプションの拡張機能

[!IMPORTANT] CLICKHOUSE_SECURE、CLICKHOUSE_VERIFY、CLICKHOUSE_CA_CERT、CLICKHOUSE_CLIENT_CERT、CLICKHOUSE_CLIENT_CERT_KEY、CLICKHOUSE_TLS_MODE、および CLICKHOUSE_PORT は、送信先の ClickHouse データベース接続にのみ適用されます。これらは、受信側の MCP HTTP/SSE エンドポイントの TLS、クライアント証明書、ポート、または認証を設定するものではありません。

例: MCP サーバーが TLS を終端する ingress の背後で Kubernetes 上で実行されている場合、それは MCP トランスポートの関心事です。CLICKHOUSE_SECURE を、ポッドが ClickHouse 自体に到達する方法（HTTPS → true、プレーン HTTP → false）に合わせて設定してください。MCP サーバーが ingress の背後にあるからといって CLICKHOUSE_SECURE=false を設定すると、サーバーは ClickHouse に対して HTTP でダイヤルすることになり（多くの場合 HTTPS 専用ポートに対して）、サーバーログに不透明な HTTP/TLS エラーが発生します。

ClickHouse データベース接続

これらの変数は、clickhouse-connect HTTP クライアントと、run_query、list_databases、list_tables などの ClickHouse バックアップツールの動作を設定します。 mcp-clickhouse には clickhouse-connect 1.x（1.0.0 以降）が必要です。

必須変数
  • CLICKHOUSE_HOST: ClickHouse サーバーのホスト名（データベースエンドポイントであり、MCP サーバーのバインドアドレスではありません）
  • CLICKHOUSE_USER: ClickHouse 認証用のユーザー名
  • CLICKHOUSE_PASSWORD: ClickHouse 認証用のパスワード
    • CLICKHOUSE_CLIENT_CERT がデフォルトまたは "mutual" TLS モードを使用しない限り必須
    • デフォルトまたは "mutual" モードでは、証明書認証が使用され、パスワードは送信されません

[!CAUTION] MCP データベースユーザーは、データベースに接続する他の外部クライアントと同様に扱い、その操作に必要な最小限の権限のみを付与することが重要です。デフォルトユーザーや管理ユーザーの使用は常に厳密に避ける必要があります。

オプション変数
  • CLICKHOUSE_PORT: ClickHouse サーバーの HTTP インターフェースポート
    • デフォルト: 8443（CLICKHOUSE_SECURE=true の場合）、8123（CLICKHOUSE_SECURE=false の場合）
    • 通常は非標準ポートを使用しない限り設定する必要はありません
    • HTTP インターフェースポートである必要があります。clickhouse-client で使用されるネイティブ TCP プロトコルポートではありません
    • 一般的な値:
      • HTTP: 8123（プレーン）/ 8443（TLS）— このサーバーと ClickHouse Cloud HTTPS で使用
      • ネイティブ TCP（ここではサポートされていません）: 9000（プレーン）/ 9440（TLS）— clickhouse-client で使用
    • サーバーが Port 9000 is for clickhouse-client program で応答する場合、ネイティブプロトコルを指しています。HTTP ポート（8123/8443 またはデプロイメントの HTTP マッピング）に切り替えてください
  • CLICKHOUSE_ROLE: 認証に使用する ClickHouse ロール
    • デフォルト: None
    • ユーザーが特定のロールを必要とする場合に設定します
  • CLICKHOUSE_SECURE: ClickHouse データベース接続の HTTPS を有効にする（MCP クライアント用ではありません）
    • デフォルト: "true"
    • MCP サーバーがプレーン HTTP で ClickHouse に到達する場合にのみ "false" に設定します（ポート 8123 のローカル Docker Compose で一般的）
    • ClickHouse Cloud および HTTPS データベースエンドポイントでは "true" のままにします。MCP サーバー自体が HTTP、stdio、または TLS を個別に終端する ingress 経由で公開されている場合でも同様です
    • このフラグとデータベースポートの不一致（例: ポート 8443 に対する CLICKHOUSE_SECURE=false）は頻繁な設定ミスであり、通常は明確な「スキームが間違っている」メッセージではなく、紛らわしい HTTP クライアントエラーとして表面化します
  • CLICKHOUSE_VERIFY: ClickHouse HTTPS 接続の SSL 証明書検証を有効/無効にする
    • デフォルト: "true"
    • 証明書検証を無効にするには "false" に設定します（本番環境では推奨されません）
    • TLS 証明書: パッケージは起動時に truststore.inject_into_ssl() を介してオペレーティングシステムのトラストストアを使用します。MCP_CLICKHOUSE_TRUSTSTORE_DISABLE=1 で注入が無効になっている場合、または失敗した場合は、Python のデフォルトの SSL 処理が使用されます
  • MCP_CLICKHOUSE_TRUSTSTORE_DISABLE: TLS のプロセス全体のオペレーティングシステムトラストストア統合を無効にする
    • デフォルト: 未設定（トラストストア統合は有効）
    • 起動前に正確に "1" に設定すると、truststore.inject_into_ssl() をスキップし、Python のデフォルトの SSL 証明書処理を使用します。他の値では統合は無効になりません
    • これは証明書検証を無効にするものではありません。CLICKHOUSE_VERIFY が引き続き ClickHouse HTTPS 接続の検証を制御します
  • CLICKHOUSE_CA_CERT: ClickHouse HTTPS 接続用の PEM CA 証明書バンドルへのパス
    • デフォルト: None（トラストストア注入が無効または失敗しない限り、オペレーティングシステムのトラストストアを使用）
    • ClickHouse サーバーまたはプライベートプロキシがプライベート CA によって署名された証明書を提示する場合に、これを単独で使用します。これによりサーバー証明書の検証が変更され、クライアント証明書認証は有効になりません
    • CLICKHOUSE_SECURE=true と CLICKHOUSE_VERIFY=true が必要です
  • CLICKHOUSE_CLIENT_CERT: ClickHouse HTTPS 接続用の PEM クライアント証明書へのパス
    • デフォルト: None
    • ファイルに秘密鍵が含まれている場合もあります。それ以外の場合は CLICKHOUSE_CLIENT_CERT_KEY を設定します
    • ClickHouse ユーザーは引き続き CLICKHOUSE_USER から取得されます
  • CLICKHOUSE_CLIENT_CERT_KEY: CLICKHOUSE_CLIENT_CERT 用の PEM 秘密鍵へのパス
    • デフォルト: None
    • 秘密鍵がクライアント証明書ファイルに含まれている場合はオプション
    • CLICKHOUSE_CLIENT_CERT なしでは使用できません
  • CLICKHOUSE_TLS_MODE: clickhouse-connect が CLICKHOUSE_CLIENT_CERT をどのように使用するか
    • デフォルト: None。クライアント証明書が設定されている場合、"mutual" として動作します
    • "mutual": ClickHouse X.509 ユーザー認証にクライアント証明書を使用します。CLICKHOUSE_PASSWORD はオプションであり、送信されません
    • "proxy": TLS 終端プロキシにクライアント証明書を提示し、ClickHouse Basic 認証を使用します。CLICKHOUSE_PASSWORD が必要です
    • "strict": ClickHouse サーバーが TLS レイヤーでクライアント証明書を要求するため提示し、ClickHouse Basic 認証を使用します。CLICKHOUSE_PASSWORD が必要です。このモードはサーバー証明書の検証を強化しません。CLICKHOUSE_VERIFY がその検証を制御します
    • clickhouse-connect は "proxy" と "strict" を同一に扱います。2 つの名前は意図を文書化するためのものです
    • 値はトリミングされ、大文字と小文字は区別されません。空白の値は未設定として扱われます。その他の値は、ClickHouse クライアントが作成される前に、最初の ClickHouse ツール呼び出しまたは /health プローブで拒否されます
    • CLICKHOUSE_CLIENT_CERT が必要です。すべてのクライアント証明書オプションには CLICKHOUSE_SECURE=true が必要です
  • CLICKHOUSE_SERVER_HOST_NAME: ClickHouse 接続の SNI オーバーライドと証明書検証用のサーバーホスト名
    • デフォルト: None（接続ホスト名を使用）
    • これは、証明書のホスト名が接続ホスト名と異なるプロキシやロードバランサーを介して接続する場合に便利です。設定すると、このホスト名は TLS ハンドシェイク中の SNI（サーバー名表示）と証明書ホスト名検証の両方に使用されます
  • CLICKHOUSE_PROXY_PATH: ClickHouse HTTP エンドポイントの URL パスプレフィックス
    • デフォルト: None
    • ClickHouse HTTP インターフェースがリバースプロキシの背後でパスプレフィックス付きで公開されている場合に設定します（例: /clickhouse）
  • CLICKHOUSE_CONNECT_TIMEOUT: ClickHouse クライアントの接続タイムアウト（秒）
    • デフォルト: "30"
    • 接続タイムアウトが発生する場合はこの値を増やします
  • CLICKHOUSE_SEND_RECEIVE_TIMEOUT: ClickHouse クライアントの送受信タイムアウト（秒）
    • デフォルト: 300 または CLICKHOUSE_MCP_QUERY_TIMEOUT + 5 の低い方。ワーカースレッドがクエリタイムアウトの直後にブロック解除されるようにします
    • 明示的に設定した場合、値はそのまま使用されます（例: 長時間実行クエリの場合は "300"）
  • CLICKHOUSE_DATABASE: 使用するデフォルトの ClickHouse データベース
    • デフォルト: None（サーバーのデフォルトを使用）
    • 特定のデータベースに自動的に接続するにはこれを設定します
  • CLICKHOUSE_ENABLED: ClickHouse データベースツールを有効/無効にする
    • デフォルト: "true"
    • chDB のみを使用する場合に ClickHouse ツールを無効にするには "false" に設定します
  • CLICKHOUSE_ALLOW_WRITE_ACCESS: ClickHouse への書き込み操作（DDL および DML）を許可する
    • デフォルト: "false"
    • 非破壊的な DDL および DML（CREATE、INSERT、ALTER ADD COLUMN）を許可するには "true" に設定します。破壊的なステートメントにはさらに CLICKHOUSE_ALLOW_DROP=true が必要です
    • 無効（デフォルト）の場合、クエリはデータ変更を防ぐために readonly=1 設定で実行されます
  • CLICKHOUSE_ALLOW_DROP: 破壊的操作を許可する（任意の DROP または TRUNCATE、DELETE と UPDATE（ALTER TABLE バリアントを含む）、REPLACE TABLE / REPLACE PARTITION / CREATE OR REPLACE、CLEAR COLUMN / CLEAR INDEX / CLEAR PROJECTION、および DETACH ... PERMANENTLY）
    • デフォルト: "false"
    • CLICKHOUSE_ALLOW_WRITE_ACCESS=true も設定されている場合にのみ有効になります
    • このゲートは MCP サーバー内のベストエフォートの事故防止ガードであり、セキュリティ境界ではありません。実際の強制には ClickHouse ユーザーの権限を制限してください（破壊的操作の保護を参照）
ClickHouse TLS 証明書ファイル

証明書の変数にはファイルパスが含まれており、PEMコンテンツではありません。mcp-clickhouseはこれらのパスをclickhouse-connectに渡します。DockerやKubernetesの場合は、証明書と秘密鍵を読み取り専用ファイルとしてマウントし、コンテナ内のパスを使用してください。秘密鍵をイメージに焼き込んだり、ソース管理にコミットしたり、環境変数にその内容を入れたりしないでください。

mutual モードでは、設定されたクライアント証明書がこのmcp-clickhouseプロセスを CLICKHOUSE_USER として識別します。インバウンドのMCPクライアントを認証したり、そのIDをClickHouseに渡したりすることはありません。MCPトランスポートの認証は別途設定してください。

同じパスで証明書またはキーを交換した後、即時のローテーションや失効が必要な場合は、mcp-clickhouseを再起動してください。キャッシュされたクライアントは既存のTLS接続を保持できる場合があり、キャッシュはファイルの内容や変更時刻を追跡しません。

ClickHouse Cloudは、データベースユーザーに対するX.509クライアント証明書認証をサポートしていません。ClickHouse Cloudには CLICKHOUSE_USER と CLICKHOUSE_PASSWORD を使用してください。エンドポイントの前にあるプライベートプロキシがプライベートCAによって署名された証明書を提示する場合、CA証明書は依然として役立つことがあります。

MCPサーバーとトランスポート

これらの変数は、トランスポート、認証、クエリツールの実行制限を含むMCPプロセス自体を制御します。これらは上記のClickHouseデータベース設定とは独立しています。HTTP/SSEトランスポートの認証も参照してください。

  • CLICKHOUSE_MCP_SERVER_TRANSPORT: MCPサーバーのトランスポート方式を設定します
    • デフォルト: "stdio"
    • 有効なオプション: "stdio"、"http"、"sse"。これはMCP Inspectorなどのツールを使ったローカル開発に便利です。
    • stdio はClaude Desktopで一般的です。http/sse はネットワークリスナーを公開します（バインドホスト/ポートは下記参照）
    • "sse" は非推奨のスタンドアロンHTTP+SSEトランスポートを選択し、警告をログに記録します。新しいデプロイメントではStreamable HTTPに "http" を使用してください。
  • CLICKHOUSE_MCP_BIND_HOST: HTTPまたはSSEトランスポート使用時にMCPサーバーをバインドするホスト
    • デフォルト: "127.0.0.1"
    • すべてのネットワークインターフェースにバインドするには "0.0.0.0" に設定します（Dockerやリモートアクセスに便利）
    • トランスポートが "http" または "sse" の場合のみ使用されます — CLICKHOUSE_HOST とは関係ありません
  • CLICKHOUSE_MCP_BIND_PORT: HTTPまたはSSEトランスポート使用時にMCPサーバーをバインドするポート
    • デフォルト: "8000"
    • トランスポートが "http" または "sse" の場合のみ使用されます — CLICKHOUSE_PORT とは関係ありません
  • CLICKHOUSE_MCP_QUERY_TIMEOUT: クエリツール呼び出しのタイムアウト（秒）
    • デフォルト: "30"
    • 重いクエリで Query timed out after ... エラーが発生する場合はこれを増やしてください
    • クエリがタイムアウトすると、サーバーは KILL QUERY でキャンセルを試みます
    • CLICKHOUSE_SEND_RECEIVE_TIMEOUT が明示的に設定されていない限り、HTTP読み取りタイムアウトはこの値に5秒を加えた値に制限されます
  • CLICKHOUSE_MCP_MAX_WORKERS: 同時クエリワーカースレッドの最大数
    • デフォルト: "10"
    • 多くの同時ツール呼び出しが必要なワークロードの場合は増やしてください
    • メタデータツールは min(4, CLICKHOUSE_MCP_MAX_WORKERS) スレッドの別のプールを使用するため、スキーマ検出がクエリを遅延させることはありません
  • CLICKHOUSE_MCP_AUTH_TOKEN: HTTP/SSEトランスポート用の静的ベアラートークン
    • デフォルト: なし
    • CLICKHOUSE_MCP_AUTH_TOKEN、FASTMCP_SERVER_AUTH、または CLICKHOUSE_MCP_AUTH_DISABLED=true のいずれかがHTTP/SSEトランスポートには必須です
    • uuidgen または openssl rand -hex 32 を使用して生成してください
    • クライアントはこのトークンを Authorization: Bearer <token> ヘッダーで送信する必要があります
  • FASTMCP_SERVER_AUTH: FastMCP認証プロバイダーに認証を委任します
    • デフォルト: なし
    • 値はAuthProviderサブクラスの完全なクラスパスです。例: fastmcp.server.auth.providers.azure.AzureProvider または fastmcp.server.auth.providers.google.GoogleProvider
    • 設定すると、mcp-clickhouseは既存の FASTMCP_SERVER_AUTH_* 環境変数からプロバイダーを読み込みます。このモードでは CLICKHOUSE_MCP_AUTH_TOKEN は未設定のままにしてください
    • カスタムプロバイダーは環境から派生したコンストラクター引数を受け取らず、引数なしの構築をサポートする必要があります
    • FastMCP 4はSupabase HS256検証をサポートしなくなりました。SupabaseデプロイメントはRS256またはES256を使用する必要があります。
  • FASTMCP_ENV_FILE: FASTMCP_SERVER_AUTH とプロバイダー固有の環境変数を含むオプションのファイル
    • デフォルト: なし。未設定の場合、互換性ローダーは作業ディレクトリの .env から欠落しているプロバイダーフィールドを読み取ります。そのフォールバックから FASTMCP_SERVER_AUTH を読み取ることはありません
    • 起動前にプロセス環境で設定してください。デフォルトの .env から読み込まれた値は互換性ローダーをリダイレクトできません
    • プロセスで設定された場合、このファイルは FASTMCP_SERVER_AUTH とプロバイダーフィールドの両方を提供でき、作業ディレクトリのフォールバックを置き換えます
    • プロセス環境の値は大文字と小文字を区別せず優先されます
    • mcp-clickhouse互換性ローダーは、HTTP/SSE認証を構築するときのみこのファイルを読み取り、FASTMCP_SERVER_AUTH と FASTMCP_SERVER_AUTH_* エントリのみを読み取ります。FastMCP 4はより広範な設定のために同じファイルを読み取る場合があります
    • デフォルトの .env の読み込みは別です。インストールされた mcp_clickhouse パッケージディレクトリから開始し、シンボリックリンクを解決し、ファイルシステムのルートまで上方向に移動し、最初に見つかった .env を読み込むか、何も読み込みません。起動方法に関係なく、作業ディレクトリを読み取ることはありません。そのファイルは FASTMCP_SERVER_AUTH とプロバイダーフィールドを他のサーバー設定とともに提供する場合があります。ソースチェックアウトは通常、リポジトリルートの .env を見つけます
  • CLICKHOUSE_MCP_AUTH_DISABLED: HTTP/SSEトランスポートの認証を無効にします
    • デフォルト: "false"（認証は有効）
    • ローカル開発/テスト専用に認証を無効にするには "true" に設定します
    • 警告: ローカル開発にのみ使用してください。ネットワークに公開する場合は無効にしないでください
  • CLICKHOUSE_MCP_ALLOWED_HOSTS: HTTP/SSEサーバーが応答するカンマ区切りの Host ヘッダー値
    • ループバックバインドのデフォルト: 127.0.0.1、localhost、[::1] のベア形式と任意ポート形式
    • 設定する場合、値には少なくとも1つのHostエントリが含まれている必要があります。
    • 具体的な非ループバックバインドアドレスは、そのアドレスと設定されたポートにデフォルト設定されます。0.0.0.0 や :: などのワイルドカードバインドは、パブリックHostを推測できないため、明示的な非空の値が必要です。
    • Host検証はDNSリバインディングに対する多層防御です。以下のOrigin検証はMCPによって別途必要です。
    • エントリは完全一致（localhost:8000）または任意のポートを受け入れます（localhost:*）。例: CLICKHOUSE_MCP_ALLOWED_HOSTS=127.0.0.1:8000,localhost:8000
    • host:* 形式はポートを持つ値のみに一致します。ポートなしのHost（クライアントが :80/:443 を省略する標準ポートのデプロイメント）は、ベアの完全一致エントリ（example.com）としてもリストする必要があります。
    • 一致しないまたは欠落している Host ヘッダーを持つリクエストは 421 Misdirected Request を受け取ります。/health へのGETおよびHEADリクエストは、オーケストレータのプローブが機能し続けるように、HostおよびOrigin検証から除外されます。
    • リバースプロキシの背後では、元の Host ヘッダーを保持することをお勧めします。代わりに、プロキシが送信するアップストリームの Host 値をリストすることもできます。fastmcp run などのランチャーがリモートアクセス用にバインドアドレスを上書きする場合は、明示的なリストを設定してください。
    • mcp-clickhouseはFastMCPの個別のHostおよびOriginガードを強制的にオフにします。FASTMCP_HTTP_HOST_ORIGIN_PROTECTION、FASTMCP_HTTP_ALLOWED_HOSTS、FASTMCP_HTTP_ALLOWED_ORIGINS は適用されません。CLICKHOUSE_MCP_ALLOWED_HOSTS と CLICKHOUSE_MCP_ALLOWED_ORIGINS が権威を持ちます。
  • CLICKHOUSE_MCP_TRUSTED_PROXIES: X-Forwarded-* ヘッダーが信頼されるプロキシIPアドレスまたはCIDRネットワーク
    • デフォルト: なし。X-Forwarded-Host は無視されます。X-Forwarded-For と X-Forwarded-Proto の既存のUvicorn処理は変更されません。
    • エントリはIPアドレスまたはCIDRネットワークである必要があります（例: 127.0.0.1,10.20.0.0/24,2001:db8::1）。CIDRはネットワークアドレスを使用する必要があるため、10.20.0.1/24 は拒否されます。ホスト名、スコープ付きIPv6アドレス、*、0.0.0.0/0、::/0 も拒否されます。
    • 信頼は直接の生ソケットピアに基づきます。他のピアからのリクエスト、またはクライアントアドレスのないリクエストは、X-Forwarded-Host を無視し、Host を検証します。
    • 信頼されたピアは、1つの非空の値を含む正確に1つの X-Forwarded-Host ヘッダーを送信できます。重複フィールド、空の値、カンマ区切りのリストは 421 Misdirected Request を受け取ります。ヘッダーがない場合、Host が検証されます。
    • 可能な限り狭いアドレスまたはネットワークを使用してください。MCPサーバーは設定された範囲のプロキシを通じてのみ到達可能である必要があります。すべての信頼されたプロキシは、クライアント提供の X-Forwarded-Host と X-Forwarded-Proto 値を削除して上書きし、検証された接続ピアから X-Forwarded-For を構築する必要があります。
    • 組み込みサーバーと fastmcp run はUvicornの外側のプロキシヘッダー処理を無効にし、生のピアからHostを検証してから、X-Forwarded-For と X-Forwarded-Proto を適用します。このモードで uvicorn_config["proxy_headers"] を明示的に有効にすると起動に失敗します。
    • 直接のASGI埋め込みでは、外側のASGIサーバーでプロキシヘッダー処理を無効にし、mcp.http_app(raw_client_address_preserved=True) を呼び出す必要があります。その明示的なアサーションがないと、信頼されたプロキシが設定されている場合、アプリの構築は失敗します。
  • CLICKHOUSE_MCP_ALLOWED_ORIGINS: HTTP/SSEで受け入れられるカンマ区切りの Origin ヘッダー値
    • デフォルト: なし。Origin ヘッダーを持つすべてのリクエストを拒否します
    • MCPはHTTP/SSEトランスポート接続にOrigin検証を要求します。Originのないリクエストは、非ブラウザのMCPクライアントが通常それを省略するため受け入れられます。一致しないOriginは 403 Forbidden を受け取ります。/health エンドポイントは上記のとおり除外されます。
    • エントリは完全一致（http://localhost:3000）または任意のポートを受け入れます（http://localhost:*）。ホストと同様に、任意ポート形式はポートを持つオリジンのみに一致します。標準ポートのオリジン（https://app.example.com）は正確にリストする必要があります。
リバースプロキシのHost処理

可能な場合は Host を保持してください。これにより、転送されたHostの信頼が無効のままになります:

location / {
    proxy_pass http://mcp-clickhouse:8000;
    proxy_set_header Host $http_host;
    proxy_set_header X-Forwarded-Host "";
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;
}

X-Forwarded-For と X-Forwarded-Proto を X-Forwarded-Host の信頼とは独立してサニタイズします。Uvicornは CLICKHOUSE_MCP_TRUSTED_PROXIES が未設定の場合でも、プロキシピアに基づいてこれらのヘッダーを信頼する場合があります。

CLICKHOUSE_MCP_ALLOWED_HOSTS=mcp.example.com

標準のnginxは、プロキシされたリクエストの Host をアップストリーム名に変更します。X-Forwarded-Host を作成または上書きしません。Host の保持が不可能な場合は、信頼されたエッジで転送されたヘッダーを上書きします:

location / {
    proxy_pass http://mcp-clickhouse:8000;
    proxy_set_header X-Forwarded-Host $http_host;
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;
}

CLICKHOUSE_MCP_ALLOWED_HOSTS=mcp.example.com
CLICKHOUSE_MCP_TRUSTED_PROXIES=10.20.0.8

2番目の設定は、10.20.0.8 がプロキシの直接の送信元アドレスであり、サーバーポートが他のクライアントから分離されており、nginxが示されているように受信転送ヘッダーを上書きする場合にのみ安全です。プロキシチェーンの場合、各信頼されたホップは、新しい転送ヘッダーを構築する前に、未検証の受信値を破棄する必要があります。

IPv6またはデュアルスタックバインドでは、IPv4プロキシが ::ffff:10.20.0.8 などのIPv4マップアドレスとして表示される場合があります。これらは自動的にIPv4エントリと照合されます。Envoyの append_x_forwarded_host は既存の X-Forwarded-Host に上書きではなく追加するため、拒否されるカンマ区切りのリストが生成されます。したがって、信頼されたホップが代わりにヘッダーを上書きするように設定してください。ソースNATを使用するKubernetes（例: externalTrafficPolicy: Cluster）では、観測されるピアがプロキシポッドではなくノードIPの場合があるため、適切にポッドまたはノードCIDRを信頼してください。ingress-nginxは Host と X-Forwarded-Host の両方を自身で上書きします。

ミドルウェア変数

  • MCP_MIDDLEWARE_MODULE: MCPサーバーに注入するカスタムミドルウェアを含むPythonモジュール名
    • デフォルト: なし（ミドルウェアは読み込まれません）
    • ミドルウェアモジュールのモジュール名（.py 拡張子なし）に設定します
    • モジュールは setup_middleware(mcp) 関数を提供する必要があります
    • 詳細と例についてはカスタムミドルウェアを参照してください

chDB変数

  • CHDB_ENABLED: chDB機能の有効化/無効化
    • デフォルト: "false"
    • "true" に設定するとchDBツールが有効になります
    • オプションの追加パッケージのインストールが必要です: mcp-clickhouse[chdb]
  • CHDB_DATA_PATH: chDBデータディレクトリへのパス
    • デフォルト: ":memory:" (インメモリデータベース)
    • インメモリデータベースには :memory: を使用します
    • 永続ストレージにはファイルパスを使用します (例: /path/to/chdb/data)

よくある設定の落とし穴

  • CLICKHOUSE_SECURE と MCP / イングレスTLSの比較 — MCPサーバーがKubernetesイングレス、リバースプロキシの背後にある、またはプレーンHTTP経由で到達されるために CLICKHOUSE_SECURE をオフにしても、データベースのTLSは無効になりません。これはこのプロセスがClickHouseに接続する方法を変更するだけです。イングレスのTLSはデータベースクライアント設定とは別に設定してください。
  • ネイティブプロトコルポート — CLICKHOUSE_PORT はClickHouseのHTTPインターフェース (デフォルトでは 8123/8443) をターゲットにする必要があります。ポート 9000/9440 はネイティブTCPプロトコル (clickhouse-client) 用であり、このサーバーでは機能しません。
  • ホストの混同 — CLICKHOUSE_HOST はデータベースのホスト名です。CLICKHOUSE_MCP_BIND_HOST はMCP HTTP/SSEサーバーがリッスンするアドレスにすぎません。

設定例

Dockerを使用したローカル開発の場合:

# Required variables
CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse

# Optional: Override defaults for local development
CLICKHOUSE_SECURE=false  # Uses port 8123 automatically
CLICKHOUSE_VERIFY=false

ClickHouse Cloudの場合:

# Required variables
CLICKHOUSE_HOST=your-instance.clickhouse.cloud
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=your-password

# Optional: These use secure defaults
# CLICKHOUSE_SECURE=true  # Uses port 8443 automatically
# CLICKHOUSE_DATABASE=your_database

ClickHouse SQL Playgroundの場合:

CLICKHOUSE_HOST=sql-clickhouse.clickhouse.com
CLICKHOUSE_USER=demo
CLICKHOUSE_PASSWORD=
# Uses secure defaults (HTTPS on port 8443)

クライアント証明書認証なしのプライベートサーバーCAの場合:

CLICKHOUSE_HOST=your-secure-clickhouse.example.com
CLICKHOUSE_USER=your-user
CLICKHOUSE_PASSWORD=your-password
CLICKHOUSE_SECURE=true
CLICKHOUSE_VERIFY=true
CLICKHOUSE_CA_CERT=/run/secrets/clickhouse-ca.pem

ClickHouse X.509クライアント証明書認証の場合:

CLICKHOUSE_HOST=your-secure-clickhouse.example.com
CLICKHOUSE_USER=your-certificate-user
CLICKHOUSE_SECURE=true
CLICKHOUSE_CLIENT_CERT=/run/secrets/clickhouse-client.pem
CLICKHOUSE_CLIENT_CERT_KEY=/run/secrets/clickhouse-client-key.pem
# CLICKHOUSE_CA_CERT=/run/secrets/clickhouse-ca.pem  # Only for a private server CA
# CLICKHOUSE_TLS_MODE=mutual  # Optional. This is the default with a client certificate.

ClickHouseがBasic認証を使用している一方で、厳格なTLSサーバーがクライアント証明書を要求する場合:

CLICKHOUSE_HOST=your-secure-clickhouse.example.com
CLICKHOUSE_USER=your-user
CLICKHOUSE_PASSWORD=your-password
CLICKHOUSE_SECURE=true
CLICKHOUSE_CLIENT_CERT=/run/secrets/clickhouse-client.pem
CLICKHOUSE_CLIENT_CERT_KEY=/run/secrets/clickhouse-client-key.pem
CLICKHOUSE_TLS_MODE=strict

TLS終端プロキシがクライアント証明書を要求し、ClickHouseが依然としてBasic認証を使用する場合は、代わりに CLICKHOUSE_TLS_MODE=proxy を使用します。

chDBのみの場合 (インメモリ):

# chDB configuration
CHDB_ENABLED=true
CLICKHOUSE_ENABLED=false
# CHDB_DATA_PATH defaults to :memory:

永続ストレージ付きchDBの場合:

# chDB configuration
CHDB_ENABLED=true
CLICKHOUSE_ENABLED=false
CHDB_DATA_PATH=/path/to/chdb/data

MCP InspectorまたはHTTPトランスポートを使用したリモートアクセスの場合:

CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse
CLICKHOUSE_MCP_SERVER_TRANSPORT=http
CLICKHOUSE_MCP_BIND_HOST=0.0.0.0  # Bind to all interfaces
CLICKHOUSE_MCP_BIND_PORT=4200  # Custom port (default: 8000)
CLICKHOUSE_MCP_AUTH_TOKEN=your-generated-token  # One auth mode required for HTTP/SSE (or FASTMCP_SERVER_AUTH, or CLICKHOUSE_MCP_AUTH_DISABLED=true)
CLICKHOUSE_MCP_ALLOWED_HOSTS=127.0.0.1:4200,localhost:4200,mcp.example.com:4200  # Include every Host value clients and proxies send

HTTPトランスポートを使用したローカル開発の場合 (認証無効):

CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse
CLICKHOUSE_MCP_SERVER_TRANSPORT=http
CLICKHOUSE_MCP_AUTH_DISABLED=true  # Only for local development!
CLICKHOUSE_MCP_ALLOWED_HOSTS=127.0.0.1:8000,localhost:8000

HTTPトランスポートを使用する場合、サーバーは設定されたポート (デフォルト8000) で実行されます。たとえば、上記の設定では:

  • MCPエンドポイント: http://localhost:8000/mcp
  • ヘルスチェック: http://localhost:8000/health

これらの変数は、環境、.env ファイル、またはClaude Desktop設定で設定できます:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.12",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_DATABASE": "<optional-database>",
        "CLICKHOUSE_MCP_SERVER_TRANSPORT": "stdio",
        "CLICKHOUSE_MCP_BIND_HOST": "127.0.0.1",
        "CLICKHOUSE_MCP_BIND_PORT": "8000"
      }
    }
  }
}

注: バインドホストとポートの設定は、トランスポートが "http" または "sse" に設定されている場合にのみ使用されます。

テストの実行

uv sync --all-extras --dev # install dev dependencies
uv run ruff check . # run linting

docker compose up -d test_services # start ClickHouse
uv run pytest -v tests
uv run pytest -v tests/test_tool.py # ClickHouse only
CHDB_ENABLED=true uv run --extra chdb pytest -v tests/test_chdb_tool.py # chDB only

YouTube概要

YouTube