ClickHouse MCPサーバー
ClickHouse 用の MCP サーバー。
特徴
ツール
run_select_queryClickHouse クラスターで SQL クエリを実行します。
入力:
sql(文字列): 実行する SQL クエリ。すべての ClickHouse クエリは、安全性を確保するために
readonly = 1で実行されます。
list_databasesClickHouse クラスター上のすべてのデータベースを一覧表示します。
list_tablesデータベース内のすべてのテーブルを一覧表示します。
入力:
database(文字列): データベースの名前。
Related MCP server: MCP Alchemy
構成
次の場所にある Claude Desktop 構成ファイルを開きます。
macOSの場合:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows の場合:
%APPDATA%/Claude/claude_desktop_config.json
以下を追加します。
{
"mcpServers": {
"mcp-clickhouse": {
"command": "uv",
"args": [
"run",
"--with",
"mcp-clickhouse",
"--python",
"3.13",
"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"
}
}
}
}独自の ClickHouse サービスを指すように環境変数を更新します。
または、 ClickHouse SQL Playgroundで試してみたい場合は、次の設定を使用できます。
{
"mcpServers": {
"mcp-clickhouse": {
"command": "uv",
"args": [
"run",
"--with",
"mcp-clickhouse",
"--python",
"3.13",
"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"
}
}
}
}uvのコマンドエントリを見つけ、uv実行ファイルへの絶対パスに置き換えます。これにより、サーバーの起動時に正しいバージョンのuvが使用されるようになります。Macでは、which uvでこのパスを確認できます。変更を適用するには、Claude Desktop を再起動します。
発達
test-servicesディレクトリでdocker compose up -dを実行して ClickHouse クラスターを起動します。リポジトリのルートにある
.envファイルに次の変数を追加します。
注: このコンテキストでの
CLICKHOUSE_HOST=localhost
CLICKHOUSE_PORT=8123
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouseuv syncを実行して依存関係をインストールします。uvをインストールするにはuvこちらの手順に従ってください。その後、source .venv/bin/activate実行してください。簡単にテストするには、
mcp dev mcp_clickhouse/mcp_server.pyを実行して MCP サーバーを起動できます。
環境変数
ClickHouse 接続を構成するには、次の環境変数が使用されます。
必須変数
CLICKHOUSE_HOST: ClickHouseサーバーのホスト名CLICKHOUSE_USER: 認証用のユーザー名CLICKHOUSE_PASSWORD: 認証用のパスワード
[!注意] MCPデータベースユーザーを、データベースに接続する他の外部クライアントと同様に扱い、操作に必要な最小限の権限のみを付与することが重要です。デフォルトユーザーや管理者ユーザーの使用は、常に厳重に避けてください。
オプション変数
CLICKHOUSE_PORT: ClickHouseサーバーのポート番号デフォルト: HTTPS が有効な場合は
8443、無効な場合は8123非標準ポートを使用しない限り、通常は設定する必要はありません
CLICKHOUSE_SECURE: HTTPS接続を有効/無効にするデフォルト:
"true"安全でない接続の場合は
"false"に設定
CLICKHOUSE_VERIFY: SSL証明書検証を有効/無効にするデフォルト:
"true"証明書の検証を無効にするには
"false"に設定します（本番環境では推奨されません）
CLICKHOUSE_CONNECT_TIMEOUT: 接続タイムアウト（秒）デフォルト:
"30"接続タイムアウトが発生する場合はこの値を増やしてください
CLICKHOUSE_SEND_RECEIVE_TIMEOUT: 送受信タイムアウト（秒）デフォルト:
"300"長時間実行されるクエリの場合はこの値を増やします
CLICKHOUSE_DATABASE: 使用するデフォルトのデータベースデフォルト: なし (サーバーのデフォルトを使用)
特定のデータベースに自動的に接続するにはこれを設定します
構成例
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=falseClickHouse 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_databaseClickHouse SQL Playgroundの場合:
CLICKHOUSE_HOST=sql-clickhouse.clickhouse.com
CLICKHOUSE_USER=demo
CLICKHOUSE_PASSWORD=
# Uses secure defaults (HTTPS on port 8443)これらの変数は、環境、 .envファイル、または Claude Desktop 構成で設定できます。
{
"mcpServers": {
"mcp-clickhouse": {
"command": "uv",
"args": [
"run",
"--with",
"mcp-clickhouse",
"--python",
"3.13",
"mcp-clickhouse"
],
"env": {
"CLICKHOUSE_HOST": "<clickhouse-host>",
"CLICKHOUSE_USER": "<clickhouse-user>",
"CLICKHOUSE_PASSWORD": "<clickhouse-password>",
"CLICKHOUSE_DATABASE": "<optional-database>"
}
}
}
}テストの実行
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 testsYouTubeの概要
