MCP Clickhouse

🚀 ClickHouse MCP Server

ClickHouse用のMCPサーバーです。

✨ 主な機能

ツール

• run_select_query

  • ClickHouseクラスター上でSQLクエリを実行します。
  • 入力: sql (文字列): 実行するSQLクエリ。
  • すべてのClickHouseクエリはreadonly = 1で実行され、安全性が保証されます。

• list_databases

  • ClickHouseクラスター上のすべてのデータベースをリストします。

• list_tables

  • データベース内のすべてのテーブルをリストします。
  • 入力: database (文字列): データベースの名前。

📦 インストール

設定手順

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.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": "1800",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "1800"
      }
    }
  }
}

環境変数を自分の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": "1800",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "1800"
      }
    }
  }
}

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

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

🔧 開発

開発手順

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 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: 接続タイムアウト（秒）
  • デフォルト: "1800"
  • 接続タイムアウトが発生する場合は、この値を増やしてください。
• CLICKHOUSE_SEND_RECEIVE_TIMEOUT: 送受信タイムアウト（秒）
  • デフォルト: "1800"
  • 長時間実行されるクエリの場合は、この値を増やしてください。
• CLICKHOUSE_DATABASE: 使用するデフォルトのデータベース
  • デフォルト: なし（サーバーのデフォルトを使用）
  • 特定のデータベースに自動的に接続するには、これを設定します。

設定例

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

# 必須変数
CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse

# オプション: ローカル開発用にデフォルトを上書き
CLICKHOUSE_SECURE=false  # 自動的にポート8123を使用
CLICKHOUSE_VERIFY=false

ClickHouse Cloudの場合:

# 必須変数
CLICKHOUSE_HOST=your-instance.clickhouse.cloud
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=your-password

# オプション: セキュアなデフォルトを使用
# CLICKHOUSE_SECURE=true  # 自動的にポート8443を使用
# CLICKHOUSE_DATABASE=your_database

ClickHouse SQL Playgroundの場合:

CLICKHOUSE_HOST=sql-clickhouse.clickhouse.com
CLICKHOUSE_USER=demo
CLICKHOUSE_PASSWORD=
# セキュアなデフォルトを使用（ポート8443でHTTPS）

これらの変数は、環境、.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 # 開発用の依存関係をインストール
uv run ruff check . # リンティングを実行

docker compose up -d test_services # ClickHouseを起動
uv run pytest tests

📚 ドキュメント

YouTube概要