ClickHouse MCPサーバープロジェクト詳細

概要

ClickHouse MCPサーバーは、ClickHouse公式が開発したModel Context Protocol (MCP) サーバーの実装であり、特にAIアシスタント（Claudeなど）にClickHouseデータベースとの安全な接続とインタラクション機能を提供します。このプロジェクトは、標準化されたMCPプロトコルを通じて、AIアシスタントがSQLクエリの実行、データベース構造の管理、リアルタイムデータ分析を実行できるようにします。

MCP（Model Context Protocol）は、AIアプリケーションに安全で標準化された外部サービス統合方法を提供することを目的としたオープンスタンダードです。このサーバーを通じて、ユーザーはAIアシスタントにClickHouseデータベースへの直接アクセスを許可し、インテリジェントなデータクエリと分析を実現できます。

主要機能

1. SQLクエリ実行 (`run_select_query`)

機能説明: ClickHouseクラスター上でSQLクエリを実行します。
安全メカニズム: すべてのクエリはreadonly = 1モードで実行され、データの安全性を確保します。
入力パラメータ:
- sql (文字列): 実行するSQLクエリステートメント
使用シナリオ: データ検索、統計分析、レポート生成

2. データベース管理 (`list_databases`)

機能説明: ClickHouseクラスター内のすべてのデータベースをリスト表示します。
用途: データベース構造の探索、権限検証
戻り内容: アクセス可能なデータベースのリスト

3. テーブル管理 (`list_tables`)

機能説明: 指定されたデータベース内のすべてのテーブルをリスト表示します。
入力パラメータ:
- database (文字列): データベース名
用途: テーブル構造の探索、データモデルの理解

設定とデプロイ

Claude Desktop統合

macOS設定パス

~/Library/Application Support/Claude/claude_desktop_config.json

Windows設定パス

%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_HOST: ClickHouseサーバーのホスト名
CLICKHOUSE_USER: 認証ユーザー名
CLICKHOUSE_PASSWORD: 認証パスワード

オプション変数

CLICKHOUSE_PORT: ポート番号
- デフォルト: HTTPS有効時は8443、無効時は8123
CLICKHOUSE_SECURE: HTTPS接続の有効/無効
- デフォルト: "true"
CLICKHOUSE_VERIFY: SSL証明書検証の有効/無効
- デフォルト: "true"
CLICKHOUSE_CONNECT_TIMEOUT: 接続タイムアウト時間（秒）
- デフォルト: "30"
CLICKHOUSE_SEND_RECEIVE_TIMEOUT: 送信/受信タイムアウト時間（秒）
- デフォルト: "300"
CLICKHOUSE_DATABASE: デフォルトで接続するデータベース
- デフォルト: なし（サーバーのデフォルトを使用）

使用シナリオ

1. ClickHouse SQL演習場設定

{
  "env": {
    "CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
    "CLICKHOUSE_PORT": "8443",
    "CLICKHOUSE_USER": "demo",
    "CLICKHOUSE_PASSWORD": "",
    "CLICKHOUSE_SECURE": "true",
    "CLICKHOUSE_VERIFY": "true"
  }
}

2. ローカル開発環境設定

# .envファイル設定
CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse
CLICKHOUSE_SECURE=false
CLICKHOUSE_VERIFY=false

3. ClickHouse Cloud設定

CLICKHOUSE_HOST=your-instance.clickhouse.cloud
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=your-password
# 安全なデフォルト設定を使用

開発とテスト

環境準備

# 依存関係のインストール
uv sync

# 仮想環境のアクティブ化
source .venv/bin/activate

# 開発サーバーの起動
mcp dev mcp_clickhouse/mcp_server.py

テストフロー

# 開発依存関係のインストール
uv sync --all-extras --dev

# コードチェック
uv run ruff check .

# テストサービスの起動
docker compose up -d test_services

# テストの実行
uv run pytest tests

安全性に関する考慮事項

データベース権限管理

最小権限の原則: MCPデータベースユーザーは、必要な最小限の権限のみを持つべきです。
管理者アカウントの回避: デフォルトまたは管理者ユーザーの使用は厳禁です。
読み取り専用モード: すべてのクエリは読み取り専用モードで実行され、データの変更を防ぎます。

ネットワークセキュリティ

HTTPS接続: 本番環境ではHTTPSを有効にすることをお勧めします。
証明書検証: SSL証明書検証を有効にして、接続の安全性を確保します。
タイムアウト設定: 接続とクエリのタイムアウトを適切に設定し、リソースの占有を防ぎます。

技術特性

互換性

Pythonバージョン: Python 3.13をサポート
依存関係管理: uvを使用してパッケージ管理
コンテナ化: Dockerデプロイをサポート
クロスプラットフォーム: macOS、Windows、Linuxをサポート

パフォーマンス最適化

接続プール: 効率的なデータベース接続管理
タイムアウト制御: 設定可能な接続とクエリのタイムアウト
非同期サポート: 非同期クエリ実行をサポート

まとめ

ClickHouse MCPサーバープロジェクトは、AIアシスタントとClickHouseデータベースの間に安全で効率的な橋を架けます。標準化されたMCPプロトコルを通じて、AIアシスタントは複雑なデータベース構造を理解して操作し、高度なSQLクエリを実行し、リアルタイムのデータ洞察を提供できます。

主な利点

公式サポート: ClickHouse公式によってメンテナンスされ、互換性と安定性を確保
安全設計: 組み込みの読み取り専用モードと権限制御により、データの安全性を保護
容易な統合: 標準化されたMCPプロトコルにより、AIアプリケーションの統合を簡素化
柔軟な設定: ローカル開発からクラウド本番まで、さまざまなデプロイシナリオをサポート
開発フレンドリー: 充実した開発ツールチェーンとテストフレームワーク

適用シナリオ

データ分析: AIアシスタントが複雑なデータ分析タスクを支援
ビジネスインテリジェンス: 自動化されたレポート生成とデータ洞察
リアルタイム監視: AIと組み合わせてシステムおよびビジネス指標を監視
データ探索: 自然言語クエリを通じてデータベース構造と内容を探索

このプロジェクトは、AIとデータベース統合の新しい方向性を示し、開発者に強力で安全なツールを提供し、AIアシスタントがエンタープライズレベルのデータリソースを真に理解して操作できるようにします。

mcp-clickhouse