ClickHouse MCP Server

ClickHouse MCP サーバー

ClickHouse データベースに接続し、Claude などの LLM が自然言語クエリを通じてデータを探索、分析できるようにする Model Context Protocol（MCP）サーバーです。

特長

• ClickHouse データベースに接続
• テーブルスキーマをリソースとして公開
• 自然言語の指示から SQL クエリを実行
• 読み取り専用の SQL クエリを実行
• macOS の Claude Desktop で動作

デモ

https://github.com/user-attachments/assets/b496b9b0-5955-49d5-8c26-733f34662d8f

インストール

1. このリポジトリをクローンします
2. 依存関係をインストールします。

npm install

3. .env ファイルで環境変数を設定します（.env.example を参考にしてください）。DDL および DML の実行を制限するため、読み取り専用のデータベースユーザーを使用してください
4. プロジェクトをビルドします。

npm run build

使用方法

サーバーをローカルで実行する

npm start

Claude Desktop との連携

1. Claude Desktop の設定ファイルを作成または更新します。

   • macOS の場合：~/Library/Application Support/Claude/claude_desktop_config.json

2. サーバー設定を追加します。

{
  "mcpServers": {
    "clickhouse-analytics": {
      "command": "node",
      "args": [
        "/absolute/path/to/clickhouse-mcp-server/dist/index.js"
      ],
      "env": {
        "CLICKHOUSE_URL": "your_clickhouse_url",
        "CLICKHOUSE_USERNAME": "your_username",
        "CLICKHOUSE_PASSWORD": "your_password",
        "CLICKHOUSE_DATABASE": "your_database"
      }
    }
  }
}

3. Claude Desktop を再起動します

利用可能な機能

リソース

• db://info - テーブルやスキーマなどのデータベース情報
• table://{tableName}/schema - 特定のテーブルのスキーマ
• table://{tableName}/sample - 特定のテーブルのサンプルデータ（5 行）

ツール

• execute-sql - データベースに対して読み取り専用の SQL クエリを実行
• natural-language-query - データについて自然言語で質問

セキュリティに関する考慮事項

• このサーバーでは読み取り専用の SQL クエリのみ実行できます
• 機密性の高い認証情報は環境変数に安全に保存してください
• このサーバーは、DDL または DML ステートメントの実行を防ぐため、基本的な検証を行います
• クエリの実行前に、必ずリクエストを確認してください

ライセンス

MIT