Clickhouse MCP Server

🚀 ClickHouse MCP サーバー

Model Context Protocol (MCP) サーバーです。ClickHouse データベースに接続し、Claude などの大規模言語モデルが自然言語クエリを通じてデータを探索および分析できるようにします。

✨ 主な機能

• 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