ClickHouse

公式

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

GitHub
839

Click House MCPで何ができますか？

  • 読み取り専用のSQLクエリを実行 — アシスタントに依頼して、run_queryを使用してClickHouseクラスターに対して任意のSELECTクエリを実行します。
  • データベースとテーブルの一覧表示 — list_databasesですべてのデータベースを一覧表示するか、list_tablesで特定のデータベース内のテーブルをページネーションしてスキーマを探索します。
  • chDBを介してファイルやURLに直接クエリを実行 — run_chdb_select_queryを使用して、ローカルファイルやリモートデータソースに対して、ClickHouseにロードせずにSQLを実行します。
  • 書き込みおよび破壊的操作の制御 — DDL/DMLに対してCLICKHOUSE_ALLOW_WRITE_ACCESSを有効にし、オプションでCLICKHOUSE_ALLOW_DROPを有効にして、AI支援セッション中にDROPまたはTRUNCATEステートメントを許可します。

ドキュメント

ClickHouse MCP サーバー

PyPI - Version

ClickHouse 用 MCP サーバーです。

mcp-clickhouse MCP server

機能

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 を返します。

このエンドポイントは、オーケストレータープローブ (例: Kubernetes の liveness/readiness、ロードバランサー) が認証情報なしで到達できるように、意図的に認証不要になっています。バックエンドのバージョン文字列やエラーの詳細が漏洩するのを避けるため、レスポンス本文は意図的に最小限に抑えられています。障害のデバッグはサーバーログを介して行ってください。

例:

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

セキュリティ

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

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

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

モード使用するケース環境変数
静的ベアラートークンシンプルなデプロイ、内部サービス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 エンドポイント自体に (例: MCP Inspector を使用して) アクセスするか、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>"

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

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

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

export CLICKHOUSE_MCP_AUTH_DISABLED=true

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

設定

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

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

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

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

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

破壊的操作の保護

書き込みアクセスが有効 (CLICKHOUSE_ALLOW_WRITE_ACCESS=true) な場合でも、破壊的操作 (DROP TABLE、DROP DATABASE、DROP VIEW、DROP DICTIONARY、TRUNCATE TABLE) には、安全のため追加のオプトインフラグが必要です。これにより、AI 探索中の偶発的なデータ削除を防ぎます。

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

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

この 2 層アプローチにより、偶発的な削除が非常に困難になります:

  • 書き込み操作 (INSERT、UPDATE、CREATE) には CLICKHOUSE_ALLOW_WRITE_ACCESS=true が必要です
  • 破壊的操作 (DROP、TRUNCATE) にはさらに 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 にない場合は、それらへのフルパスを使用してください。パスは以下を使用して見つけることができます:

  • 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.10", "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 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
})

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

開発

  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 で簡単にテストするには、fastmcp dev mcp_clickhouse/mcp_server.py を実行して MCP サーバーを起動します。

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

    # For development, disable authentication
CLICKHOUSE_MCP_SERVER_TRANSPORT=http CLICKHOUSE_MCP_AUTH_DISABLED=true 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

環境変数

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

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

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

例: MCP サーバーが TLS を終端するイングレスの背後にある Kubernetes で実行されている場合、それは MCP トランスポートの問題です。Pod が ClickHouse 自体に到達する方法に合わせて CLICKHOUSE_SECURE を維持してください (HTTPS → true、プレーン HTTP → false)。MCP サーバーがイングレスの背後にあるために 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 インターフェースポート
    • デフォルト: 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 ロール
    • デフォルト: なし
    • ユーザーが特定のロールを必要とする場合に設定します
  • CLICKHOUSE_SECURE: ClickHouse データベース接続 (MCP クライアント用ではない) の HTTPS を有効にする
    • デフォルト: "true"
    • MCP サーバーが平文 HTTP で ClickHouse に到達する場合 (ポート 8123 でのローカル Docker Compose が典型的) にのみ "false" に設定します
    • ClickHouse Cloud や任意の HTTPS データベースエンドポイントの場合は "true" のままにします。MCP サーバー自体が HTTP、stdio、または TLS を個別に終端するイングレス経由で公開されている場合でも同様です
    • このフラグとデータベースポートの不一致 (例: ポート 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 オーバーライドと証明書検証用のサーバーホスト名
    • デフォルト: なし (接続ホスト名を使用)
    • これは、証明書のホスト名が接続ホスト名と異なるプロキシまたはロードバランサー経由で接続する場合に役立ちます。設定すると、このホスト名が 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_DATABASE: 使用するデフォルトの ClickHouse データベース
    • デフォルト: なし (サーバーのデフォルトを使用)
    • 特定のデータベースに自動的に接続するように設定します
  • CLICKHOUSE_ENABLED: ClickHouse データベースツールを有効/無効にする
    • デフォルト: "true"
    • chDB のみを使用する場合に ClickHouse ツールを無効にするには "false" に設定します
  • CLICKHOUSE_ALLOW_WRITE_ACCESS: ClickHouse に対する書き込み操作 (DDL および DML) を許可する
    • デフォルト: "false"
    • DDL (CREATE, ALTER, DROP) および DML (INSERT, UPDATE, DELETE) 操作を許可するには "true" に設定します
    • 無効 (デフォルト) の場合、データ変更を防ぐためにクエリは readonly=1 設定で実行されます
  • CLICKHOUSE_ALLOW_DROP: 破壊的な操作 (DROP TABLE, DROP DATABASE, DROP VIEW, DROP DICTIONARY, TRUNCATE TABLE) を許可する
    • デフォルト: "false"
    • CLICKHOUSE_ALLOW_WRITE_ACCESS=true も設定されている場合にのみ有効になります
    • 破壊的な DROP および TRUNCATE 操作を明示的に許可するには "true" に設定します
    • これは、AI 探索中の偶発的なデータ削除を防ぐための安全機能です

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" に設定します
    • 警告: ローカル開発にのみ使用してください。ネットワークに公開する場合は無効にしないでください

ミドルウェア変数

  • 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)

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

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

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)

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

CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse
CLICKHOUSE_MCP_SERVER_TRANSPORT=http
CLICKHOUSE_MCP_AUTH_DISABLED=true  # Only for local development!

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

  • MCP エンドポイント: http://localhost:4200/mcp
  • ヘルスチェック: http://localhost:4200/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 の概要

YouTube