ClickHouse MCP Server

ClickHouse MCP Server

ClickHouse 用の MCP サーバーです。

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

メモ

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（string）：実行する SQL クエリです。
  • 任意の入力：params（object）：ClickHouse の {name:Type} プレースホルダーに指定する名前付きの値です。クエリパラメーターを参照してください。
  • クエリはデフォルトで読み取り専用モード（CLICKHOUSE_ALLOW_WRITE_ACCESS=false）で実行されますが、必要に応じて明示的に書き込みを有効にできます。
  • DESCRIBE (<query>) と EXPLAIN ESTIMATE <query> もここで実行でき、クエリの結果スキーマや推定読み取り量を確認する方法として任意で使用できます。実行前のクエリ確認を参照してください。

• list_databases

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

• list_tables

  • ページネーションを使用して、データベース内のテーブルを一覧表示します。
  • 必須の入力：database（string）。
  • 任意の入力：
    • like / not_like（string）：テーブル名に LIKE または NOT LIKE フィルターを適用します。
    • page_token（string）：前回の呼び出しで返された、1 回のみ使用できるトークンです。最大 1 時間保持されます。
    • page_size（int、デフォルト 50）：1 ページあたりに返されるテーブル数です。0 より大きい値を指定する必要があります。
    • include_detailed_columns（bool、デフォルト true）：false の場合、完全な create_table_query は維持したまま、応答を軽量化するために列メタデータを省略します。
  • 応答の形式：
    • tables：現在のページのテーブルオブジェクトの配列です。
    • next_page_token：有効期限が切れる前に、この 1 回のみ使用できる値を返して次のページを取得します。続きがない場合は null です。
    • total_tables：指定されたフィルターに一致するテーブルの総数です。

Agents スキーマの検出

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

クエリパラメーター

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

{
  "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、または配列を指定できます。

• Nullable(...) 型には null を使用します。
• JavaScript の安全な整数範囲を超える整数は、{id:UInt64} に対する "18446744073709551615" のように、10 進文字列で渡します。日付、タイムスタンプ、正確な小数も、対応する ClickHouse 型とともに文字列で渡すことができます。
• ベクトルは、{vector:Array(Float32)} と "params": {"vector": [0.25, 0.5, 0.75]} のように、1 つの配列としてバインドします。
• 配列内の 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 のもとで動作します。EXPLAIN ESTIMATE と DESCRIBE については、ClickHouse のドキュメントを参照してください。

chDB ツール

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

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

HTTP または SSE トランスポートで実行している場合、/health でヘルスチェックエンドポイントを利用できます。このエンドポイントは次のように動作します。

• サーバーが正常で、ClickHouse に接続できる場合は 200 OK（本文：OK）を返します
• サーバーが ClickHouse に接続できない場合は、汎用エラーメッセージとともに 503 Service Unavailable を返します
• ClickHouse のプローブが 2 秒以内に完了しない場合は 503 を返します。同時リクエストでは、実行中のプローブを共有します
• 完了したプローブ結果を 1 秒間再利用するため、短時間に続けて届いたプローブがそれぞれ ClickHouse に接続することはありません。そのため、障害や復旧の報告が最大 1 秒遅れる場合があります

このエンドポイントへの GET および HEAD リクエストは意図的に認証不要であり、Host と Origin の検証対象外です。これにより、オーケストレーターのプローブ（Kubernetes の liveness/readiness、ロードバランサーなど）は、追加設定なしでランタイムに割り当てられたポッドまたはターゲットの 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 エンドポイント自体にアクセスするか、Authorization ヘッダーの有無を変えて /mcp に 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.Auth0Provider	FASTMCP_SERVER_AUTH_AUTH0_
fastmcp.server.auth.providers.aws.AWSCognitoProvider	FASTMCP_SERVER_AUTH_AWS_COGNITO_
fastmcp.server.auth.providers.azure.AzureProvider	FASTMCP_SERVER_AUTH_AZURE_
fastmcp.server.auth.providers.descope.DescopeProvider	FASTMCP_SERVER_AUTH_DESCOPEPROVIDER_
fastmcp.server.auth.providers.discord.DiscordProvider	FASTMCP_SERVER_AUTH_DISCORD_
fastmcp.server.auth.providers.github.GitHubProvider	FASTMCP_SERVER_AUTH_GITHUB_
fastmcp.server.auth.providers.google.GoogleProvider	FASTMCP_SERVER_AUTH_GOOGLE_
fastmcp.server.auth.providers.introspection.IntrospectionTokenVerifier	FASTMCP_SERVER_AUTH_INTROSPECTION_
fastmcp.server.auth.providers.jwt.JWTVerifier	FASTMCP_SERVER_AUTH_JWT_
fastmcp.server.auth.providers.oci.OCIProvider	FASTMCP_SERVER_AUTH_OCI_
fastmcp.server.auth.providers.scalekit.ScalekitProvider	FASTMCP_SERVER_AUTH_SCALEKITPROVIDER_
fastmcp.server.auth.providers.supabase.SupabaseProvider	FASTMCP_SERVER_AUTH_SUPABASE_
fastmcp.server.auth.providers.workos.WorkOSProvider	FASTMCP_SERVER_AUTH_WORKOS_
fastmcp.server.auth.providers.workos.AuthKitProvider	FASTMCP_SERVER_AUTH_AUTHKITPROVIDER_

プレフィックスにプロバイダーのフィールド名を大文字で追加してください。各プロバイダーの設定要件については、 FastMCP docs を参照してください。

プロセス環境に直接設定された認証値は、大文字と小文字を区別せずに優先されます。 デフォルトの .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 ファイルは、どちらも信頼できる認証設定として扱ってください。パッケージ ディレクトリからファイルシステムのルートまでのいずれかのディレクトリで .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"
      }
    }
  }
}

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

4. 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 を使用して強制されます。破壊的操作のゲートはサーバー側では強制されません。

書き込みモードでは、必要な権限のみを持つ専用の ClickHouse ユーザーを MCP サーバーに設定してください。

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"
}

この二段階のアプローチにより、誤って削除してしまうリスクを抑えられます。

• 書き込み操作（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. Python を直接使用するように Claude Desktop の設定を更新します：

{
  "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())

2. 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"
      }
    }
  }
}

3. ミドルウェアモジュールが 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 クライアントの作成前に ツールの呼び出しが失敗します。上書きで明示的に settings.role が 指定されない限り、CLICKHOUSE_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 認証が行われます。

これらの上書きは、信頼できるミドルウェア入力として扱ってください。ミドルウェアは、リクエスト由来の値を設定する前に認証と認可を行う必要があります。FastMCP が値をリクエストごとの状態に保持するよう、serializable=False を使用してください。デフォルトの 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

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

4. MCP Inspector を使った簡単なテストを行うには、uv run fastmcp dev inspector mcp_clickhouse/mcp_server.py:mcp を実行して MCP サーバーを起動します。

5. 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.py	dotenv の読み込み、認証、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_FILE	MCP トランスポート、認証、クエリツールの実行制限
ミドルウェア／chDB	MCP_MIDDLEWARE_MODULE、CHDB_*	オプションの拡張機能

重要

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 トランスポートに関する設定です。Pod から ClickHouse 自体への接続方法に合わせて CLICKHOUSE_SECURE を設定してください（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 では、1.0.0 以降の clickhouse-connect 1.x が必要です。

必須変数

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

注意

MCP データベースユーザーは、データベースに接続する外部クライアントと同様に扱い、操作に必要な最小限の権限のみを付与することが重要です。デフォルトユーザーや管理者ユーザーの使用は、常に厳しく避けてください。

任意の変数

• CLICKHOUSE_PORT：ClickHouse サーバーの HTTP インターフェイスのポート
  • デフォルト：CLICKHOUSE_SECURE=true の場合は 8443、CLICKHOUSE_SECURE=false の場合は 8123
  • 標準以外のポートを使用する場合を除き、通常は設定する必要はありません
  • clickhouse-client が使用するネイティブ TCP プロトコルのポートではなく、HTTP インターフェイスのポートを指定してください
  • 一般的な値：
    • 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 ロール
  • デフォルト：なし
  • ユーザーに特定のロールが必要な場合に設定してください
• CLICKHOUSE_SECURE：ClickHouse データベース接続で HTTPS を有効にします（MCP クライアント向けではありません）
  • デフォルト："true"
  • MCP サーバーが平文 HTTP 経由で ClickHouse に接続する場合（ポート 8123 を使用するローカルの Docker Compose など）のみ、"false" に設定してください
  • ClickHouse Cloud および HTTPS データベースエンドポイントでは "true" のままにしてください。MCP サーバー自体が HTTP、stdio、または TLS を別途終端するイングレス経由で公開されている場合も同様です
  • このフラグとデータベースのポート（例：CLICKHOUSE_SECURE=false でポート 8443 に接続）の設定が一致しないことは、よくある設定ミスです。通常、明確な「スキームが間違っています」というメッセージではなく、分かりにくい 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 HTTPS 接続の検証は、引き続き CLICKHOUSE_VERIFY で制御されます。
• CLICKHOUSE_CA_CERT：ClickHouse HTTPS 接続用の PEM CA 証明書バンドルのパス
  • デフォルト：なし（truststore のインジェクションが無効または失敗していない限り、オペレーティングシステムのトラストストアを使用します）
  • ClickHouse サーバーまたはプライベートプロキシが、プライベート CA によって署名された証明書を提示する場合は、これだけを使用してください。これはサーバー証明書の検証方法を変更するものであり、クライアント証明書認証を有効にするものではありません。
  • CLICKHOUSE_SECURE=true および CLICKHOUSE_VERIFY=true が必要です
• CLICKHOUSE_CLIENT_CERT：ClickHouse HTTPS 接続用の PEM クライアント証明書のパス
  • デフォルト：なし
  • ファイルに秘密鍵を含めることもできます。含めない場合は CLICKHOUSE_CLIENT_CERT_KEY を設定してください。
  • ClickHouse のユーザーは引き続き CLICKHOUSE_USER から取得されます。
• CLICKHOUSE_CLIENT_CERT_KEY：CLICKHOUSE_CLIENT_CERT 用の PEM 秘密鍵のパス
  • デフォルト：なし
  • クライアント証明書ファイルに秘密鍵が含まれている場合は省略できます
  • CLICKHOUSE_CLIENT_CERT なしでは使用できません
• CLICKHOUSE_TLS_MODE：clickhouse-connect による CLICKHOUSE_CLIENT_CERT の使用方法
  • デフォルト：なし。クライアント証明書が設定されている場合は "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 ツール呼び出しまたは /health のプローブ時に、ClickHouse クライアントが作成される前に拒否されます。
  • CLICKHOUSE_CLIENT_CERT が必要です。すべてのクライアント証明書オプションには CLICKHOUSE_SECURE=true が必要です。
• CLICKHOUSE_SERVER_HOST_NAME：ClickHouse 接続の SNI オーバーライドおよび証明書検証に使用するサーバーのホスト名
  • デフォルト：なし（接続先のホスト名を使用します）
  • 証明書のホスト名が接続先のホスト名と異なるプロキシやロードバランサー経由で接続する場合に便利です。設定すると、TLS ハンドシェイク時の SNI（Server Name Indication）と証明書のホスト名検証の両方に、このホスト名が使用されます。
• CLICKHOUSE_PROXY_PATH：ClickHouse HTTP エンドポイントの URL パスプレフィックス
  • デフォルト：なし
  • ClickHouse HTTP インターフェイスがリバースプロキシの配下でパスプレフィックス（例：/clickhouse）を使って公開されている場合に設定してください
• CLICKHOUSE_CONNECT_TIMEOUT：ClickHouse クライアントの接続タイムアウト（秒）
  • デフォルト："30"
  • 接続タイムアウトが発生する場合は、この値を増やしてください
• CLICKHOUSE_SEND_RECEIVE_TIMEOUT：ClickHouse クライアントの送受信タイムアウト（秒）
  • デフォルト：300 と CLICKHOUSE_MCP_QUERY_TIMEOUT + 5 の小さい方です。これにより、クエリのタイムアウト後すぐにワーカースレッドのブロックが解除されます
  • 明示的に設定した場合は、その値がそのまま使用されます（例：長時間実行されるクエリでは "300"）
• CLICKHOUSE_DATABASE：使用するデフォルトの ClickHouse データベース
  • デフォルト：なし（サーバーのデフォルトを使用します）
  • 特定のデータベースに自動接続するには、これを設定してください
• 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、ALTER TABLE のバリエーションを含む DELETE および UPDATE、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 トランスポート用の静的ベアラートークン
  • デフォルト: なし
  • HTTP/SSE トランスポートでは CLICKHOUSE_MCP_AUTH_TOKEN、FASTMCP_SERVER_AUTH、または CLICKHOUSE_MCP_AUTH_DISABLED=true のいずれかが必須です
  • 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" を設定します
  • WARNING: ローカル開発にのみ使用してください。ネットワークに公開されている場合は無効にしないでください
• 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 つ含む X-Forwarded-Host ヘッダーを正確に 1 つ送信できます。重複フィールド、空の値、カンマ区切りリストは 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-Host の信頼設定とは独立して、X-Forwarded-For と X-Forwarded-Proto をサニタイズしてください。CLICKHOUSE_MCP_TRUSTED_PROXIES が未設定でも、Uvicorn はプロキシの接続元に基づいてこれらのヘッダーを信頼する場合があります。

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"
  • chDB ツールを有効にするには、"true" に設定します
  • オプションの追加機能 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 の概要