ClickHouse MCP サーバー

ClickHouse 用の MCP サーバーです。

機能

ClickHouse ツール

• run_query

  • ClickHouse クラスターに対して SQL クエリを実行します。

  • 入力: query (文字列): 実行する SQL クエリ。

  • クエリはデフォルトで読み取り専用モードで実行されます (CLICKHOUSE_ALLOW_WRITE_ACCESS=false)。ただし、必要に応じて書き込みを明示的に有効にできます。

• list_databases

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

• list_tables

  • データベース内のテーブルをページネーション付きで一覧表示します。

  • 必須入力: database (文字列)。

  • オプション入力:

    • like / not_like (文字列): テーブル名に LIKE または NOT LIKE フィルターを適用します。

    • page_token (文字列): 前回の呼び出しで返された、次のページを取得するためのトークン。

    • page_size (整数、デフォルト 50): 1 ページあたりに返されるテーブル数。

    • include_detailed_columns (ブール値、デフォルト true): false の場合、完全な create_table_query を保持しつつ、応答を軽くするためにカラムメタデータを省略します。

  • 応答の形式:

    • tables: 現在のページのテーブルオブジェクトの配列。

    • next_page_token: 次のページを取得するためにこの値を渡します。テーブルがもうない場合は null。

    • total_tables: 指定されたフィルターに一致するテーブルの総数。

chDB ツール

• run_chdb_select_query

  • chDB の組み込み ClickHouse エンジンを使用して SQL クエリを実行します。

  • 入力: query (文字列): 実行する SQL クエリ。

  • ETL プロセスなしで、さまざまなソース (ファイル、URL、データベース) からデータを直接クエリします。

  • オプションの chdb エクストラが必要です: pip install 'mcp-clickhouse[chdb]'

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

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

• サーバーが正常で ClickHouse に接続できる場合は 200 OK (ボディ: OK) を返します

• サーバーが ClickHouse に接続できない場合は、一般的なエラーメッセージとともに 503 Service Unavailable を返します

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

例:

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

Related MCP server: ClickHouse MCP Server

セキュリティ

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

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

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

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

アイデンティティプロバイダー (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>"

プロバイダーの完全なリストと、それぞれに必要な環境変数については、FastMCP ドキュメント を参照してください。

開発モード (認証の無効化)

ローカル開発とテストのみを目的として、次の設定で認証を無効にできます:

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

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

設定

この MCP サーバーは ClickHouse と chDB の両方をサポートしています。必要に応じていずれか、または両方を有効にできます。

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.10",
        "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_SEND_RECEIVE_TIMEOUT": "30"
      }
    }
  }
}

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

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

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.10",
        "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",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
      }
    }
  }
}

chDB (組み込み ClickHouse エンジン) の場合は、次の設定を追加します:

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

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

4. 変更を適用するには、Claude Desktop を再起動します。

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

デフォルトでは、この MCP は読み取り専用クエリを強制するため、探索中に誤った変更が発生することはありません。DDL または INSERT ステートメントを許可するには、CLICKHOUSE_ALLOW_WRITE_ACCESS 環境変数を true に設定します。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 コメント内のキーワードは無視されるため、チェックをトリガーすることも、ステートメントをチェックから隠すこともありません。

このチェックは 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. 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",
        "CLICKHOUSE_SEND_RECEIVE_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",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
      }
    }
  }
}

注: Python 実行ファイルまたは mcp-clickhouse スクリプトがシステムの PATH にない場合は、必ずフルパスを使用してください。パスは次のコマンドで確認できます:

• which python3: Python 実行ファイルのパス

• 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.10", "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 mcp_clickhouse.mcp_server import CLIENT_CONFIG_OVERRIDES_KEY

ctx = get_context()
ctx.set_state(CLIENT_CONFIG_OVERRIDES_KEY, {
    "connect_timeout": 60,
    "send_receive_timeout": 120
})

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

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

これらのオーバーライドは、信頼されたミドルウェア入力として扱ってください。ミドルウェアは、リクエスト由来の値を設定する前に、それらを認証および認可する必要があります。リクエストごとの 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 で簡単にテストするには、fastmcp dev mcp_clickhouse/mcp_server.py を実行して 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

環境変数

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

[!IMPORTANT] CLICKHOUSE_SECURE、CLICKHOUSE_VERIFY、CLICKHOUSE_PORT などの変数は、ClickHouse データベース接続にのみ適用されます。これらは MCP プロトコルエンドポイントの TLS、ポート、または認証を設定しません。

例: MCP サーバーが TLS を終端する ingress の背後で Kubernetes 上で実行されている場合、それは MCP トランスポートの関心事です。CLICKHOUSE_SECURE は、ポッドが ClickHouse 自体に到達する方法に合わせてください（HTTPS → true、平文 HTTP → false）。MCP サーバーが ingress の背後にあるという理由で CLICKHOUSE_SECURE=false を設定すると、サーバーは HTTP 経由で ClickHouse に接続しようとします（多くの場合、HTTPS 専用ポートに対して）。その結果、サーバーログに不透明な HTTP/TLS エラーが発生します。

ClickHouse データベース接続

これらの変数は、clickhouse-connect HTTP クライアントと、run_query、list_databases、list_tables などの ClickHouse バックエンドのツールの動作を設定します。

必須変数

• CLICKHOUSE_HOST: ClickHouse サーバーのホスト名（MCP サーバーのバインドアドレスではなく、データベースエンドポイント）

• CLICKHOUSE_USER: ClickHouse 認証用のユーザー名

• CLICKHOUSE_PASSWORD: ClickHouse 認証用のパスワード

[!CAUTION] 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 ロール

  • デフォルト: 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 を介してオペレーティングシステムのトラストストアを TLS 証明書の検証に使用します。起動時に truststore.inject_into_ssl() を呼び出して、証明書が適切に処理されるようにします。Python のデフォルトの SSL 動作は、予期しないエラーが発生した場合のフォールバックとしてのみ使用されます。

• CLICKHOUSE_SERVER_HOST_NAME: ClickHouse 接続における SNI オーバーライドと証明書検証用のサーバーホスト名

  • デフォルト: None（接続ホスト名を使用）

  • これは、証明書のホスト名が接続ホスト名と異なるプロキシやロードバランサーを介して接続する場合に便利です。設定すると、このホスト名は TLS ハンドシェイク中の SNI（Server Name Indication）と証明書のホスト名検証の両方に使用されます。

• CLICKHOUSE_PROXY_PATH: ClickHouse HTTP エンドポイントの URL パスプレフィックス

  • デフォルト: None

  • ClickHouse HTTP インターフェースがリバースプロキシの背後でパスプレフィックス（例: /clickhouse）の下に公開されている場合に設定します

• CLICKHOUSE_CONNECT_TIMEOUT: ClickHouse クライアントの接続タイムアウト（秒）

  • デフォルト: "30"

  • 接続タイムアウトが発生する場合は、この値を増やしてください

• CLICKHOUSE_SEND_RECEIVE_TIMEOUT: ClickHouse クライアントの送受信タイムアウト（秒）

  • デフォルト: "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、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 ユーザーの権限付与を制限してください（破壊的操作の保護 を参照）

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

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

• CLICKHOUSE_MCP_SERVER_TRANSPORT: MCP サーバーのトランスポート方式を設定します

  • デフォルト: "stdio"

  • 有効なオプション: "stdio"、"http"、"sse"。MCP Inspector などのツールを使ったローカル開発に便利です。

  • stdio は Claude Desktop で一般的です。http/sse はネットワークリスナーを公開します（バインドするホスト/ポートは後述）

• 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 ... エラーが発生する場合はこの値を増やしてください

• 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

  • 設定すると、FastMCP は自身の FASTMCP_SERVER_AUTH_* 環境変数からプロバイダーを自動ロードします。このモードでは CLICKHOUSE_MCP_AUTH_TOKEN は未設定のままにしてください

• 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 値をリストしてください。fastmcp run などのランチャーがリモートアクセス用にバインドアドレスを上書きする場合は、明示的なリストを設定してください。

• CLICKHOUSE_MCP_ALLOWED_ORIGINS: HTTP/SSE で受け入れる Origin ヘッダー値のカンマ区切りリスト

  • デフォルト: なし。Origin ヘッダーを持つすべてのリクエストを拒否します

  • MCP は HTTP/SSE トランスポート接続に Origin 検証を要求します。Origin なしのリクエストは、ブラウザ以外の MCP クライアントが通常これを省略するため受け入れられます。一致しない Origin は 403 Forbidden になります。/health エンドポイントは上記のとおり対象外です。

  • エントリは完全一致（http://localhost:3000）または任意ポートを受け入れる形式（http://localhost:*）です。ホストと同様に、任意ポート形式はポートを持つ Origin のみに一致します。標準ポートの Origin（https://app.example.com）は完全一致でリストする必要があります。

ミドルウェア変数

• 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 vs MCP / ingress TLS — MCP サーバーが Kubernetes ingress やリバースプロキシの背後にある、または平文 HTTP で到達されるからといって CLICKHOUSE_SECURE をオフにしても、データベースの TLS は無効になりません。これはこのプロセスが ClickHouse に接続する方法を変えるだけです。ingress の 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)

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.10",
        "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 概要