mcp-clickhouse

これは、ClickHouse 用の Model Context Protocol サーバーです。MCP 対応クライアント（Claude Desktop、Claude Code など）が、スキーマの探索、分析クエリの実行、データベースの管理をできるようにします。すべての動作はフラグによって制御されます。

セキュリティモデルはステートメント認識型です。すべてのSQLステートメントは読み取り・書き込み・破壊的のいずれかに分類され、現在のアクセスモードに基づいて制御されます。読み取り専用モードでは、さらに ClickHouse 自身の readonly=1 設定の下でクエリを実行します。

機能

• 探索とモニタリング — データベース、テーブル、カラム、SHOW CREATE、テーブル統計（パーツ/行数/バイト）、実行中クエリ、サーバーメトリクス、クラスタートポロジー。

• 読み取りクエリ — 読み取りステートメントのみを受け付ける query ツールで、CLICKHOUSE_MAX_ROWS によって上限が設定されます。

• 管理 — INSERT/CREATE/ALTER（読み書き）と DROP/TRUNCATE/DELETE（管理）用の execute ツール。それぞれ分類によって制御されます。

• アクセスモード — read-only → read-write → admin の段階で、各モードはそれ以上のレベルのステートメントを公開しません。

• セキュリティフラグ — データベースの許可リスト、保護データベース、破壊的ステートメントの制御、行数上限、ドライラン、JSON 監査ログ（下記参照）。

Related MCP server: clickhouse-mcp-server

セキュリティモデル

ステートメントの分類は src/sql.ts にあり、フェイルセーフです。ALTER … DELETE/UPDATE は破壊的として扱われ、解析できないものも破壊的として扱われます。

ツール

読み取り (read-only 以上): list_databases、list_tables、describe_table、show_create_table、table_stats、running_queries、server_metrics、cluster_info、query

書き込み/管理 (read-write 以上): execute — ステートメントを分類したうえで、単一のステートメントを実行します。書き込みには read-write モード、破壊的ステートメントには admin モードと CLICKHOUSE_ALLOW_DELETE が必要です。

MCP クライアントで利用する

Claude Code、Claude Desktop、Cursor、OpenAI Codex CLI、Windsurf、VS Code (Copilot)、その他の MCP クライアントで動作します。クライアントごとの設定は docs/CLIENTS.md を参照してください。

インストール

npm install
npm run build

Claude Desktop / Claude Code での実行

{
  "mcpServers": {
    "clickhouse": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-clickhouse/dist/index.js"],
      "env": {
        "CLICKHOUSE_URL": "http://clickhouse:8123",
        "CLICKHOUSE_USER": "readonly",
        "CLICKHOUSE_PASSWORD": "…",
        "CLICKHOUSE_MODE": "read-only",
        "CLICKHOUSE_DATABASE_ALLOWLIST": "analytics"
      }
    }
  }
}

プロンプト例

• "analytics データベースで最も大きなテーブルは何ですか？"

• "events のスキーマを表示して、今週の日次カウントを取得するクエリを実行してください。"

• "現在どのクエリが実行中で、最もメモリを使用していますか？"

開発

npm run dev
npm test          # SQL classification + security policy (30 tests)
npm run typecheck

公開

このサーバーには、公式 MCP レジストリ用の server.json と、npm 所有権検証用の mcpName が同梱されています。npm への公開、MCP レジストリ、Smithery、Glama、Cursor、PulseMCP への掲載については PUBLISHING.md を参照してください。

ライセンス

MIT