mcp-clickhouse

mcp-clickhouse

ClickHouse 向けの Model Context Protocol サーバーです。MCP 対応クライアント（Claude Desktop、Claude Code など）から、スキーマの調査、分析クエリの実行、データベースの管理を行えます。動作はすべてフラグで制御されます。

セキュリティモデルはステートメントを認識します。すべての SQL ステートメントを読み取り、書き込み、破壊的操作に分類し、現在のアクセスモードに照らして許可を判定します。読み取り専用モードでは、ClickHouse 自身の readonly=1 設定でもクエリを実行します。

機能

• 調査と監視 — データベース、テーブル、カラム、SHOW CREATE、テーブル統計（パーツ／行数／バイト数）、実行中のクエリ、サーバーメトリクス、クラスターのトポロジー。
• 読み取りクエリ — 読み取りステートメントのみを受け付け、CLICKHOUSE_MAX_ROWS を上限とする query ツール。
• 管理 — INSERT／CREATE／ALTER（読み書き）用の execute ツールと、DROP／TRUNCATE／DELETE（管理者用）。いずれも分類に基づいて許可を判定します。
• アクセスモード — read-only → read-write → admin。各モードは階層化されており、自身のレベルを超えるステートメントを許可しません。
• セキュリティフラグ — データベースの許可リスト、保護対象データベース、破壊的操作の許可、行数上限、ドライラン、JSON 監査ログ（以下を参照）。

セキュリティモデル

懸念事項	フラグ	デフォルト	効果
サーバーに許可する操作	CLICKHOUSE_MODE	read-only	read-only では読み取りツールのみを公開し（query では SELECT 以外を拒否）、read-write では書き込み用の execute を追加し、admin では破壊的ステートメントを許可します。
対象となるデータベース	CLICKHOUSE_DATABASE_ALLOWLIST	(すべて)	設定すると、その他のデータベースに対する操作を拒否します。
常に読み取り専用とするデータベース	CLICKHOUSE_PROTECTED_DATABASES	system,information_schema	読み取り可能ですが、変更できません。
破壊的な SQL の実行	CLICKHOUSE_ALLOW_DELETE	false	DROP／TRUNCATE／DELETE／…には、この設定と admin モードの両方が必要です。
結果サイズの上限	CLICKHOUSE_MAX_ROWS	1000	モデルに返す行数の上限です。
実行せずにプレビュー	CLICKHOUSE_DRY_RUN	false	書き込み／破壊的ステートメントの妥当性を確認して意図をログに記録した後、戻ります。
監査ログ	CLICKHOUSE_AUDIT_LOG	true	保護対象の操作ごとに、JSON 形式の1行を stderr に出力します。
対話形式の確認	(自動)	—	破壊的な操作と影響の大きい操作を実行する前に、MCP のエリシテーションを通じて人間に承認を求めます。エリシテーションに対応していないクライアントでは、*_ALLOW_* の許可設定にフォールバックします。

ステートメントの分類は 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 が必要です。

クイックスタート — エージェントに追加する

npm で @dockndevai/mcp-clickhouse として公開されています。クローンやビルドは不要です。MCP クライアントが必要に応じて npx で実行します。まずは read-only モードで開始してください。すべての変数については .env.example を、クライアントごとの詳しいガイドについては docs/CLIENTS.md を参照してください。

Claude Code（CLI）

claude mcp add clickhouse -e CLICKHOUSE_URL="http://localhost:8123" -e CLICKHOUSE_USER="default" -e CLICKHOUSE_MODE="read-only" -- npx -y @dockndevai/mcp-clickhouse

Claude Desktop · Cursor · Windsurf — claude_desktop_config.json、.cursor/mcp.json、または ~/.codeium/windsurf/mcp_config.json に同じブロックを記述します：

{
  "mcpServers": {
    "clickhouse": {
      "command": "npx",
      "args": [
        "-y",
        "@dockndevai/mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_URL": "http://localhost:8123",
        "CLICKHOUSE_USER": "default",
        "CLICKHOUSE_MODE": "read-only"
      }
    }
  }
}

OpenAI Codex CLI — ~/.codex/config.toml に記述します：

[mcp_servers.clickhouse]
command = "npx"
args = ["-y", "@dockndevai/mcp-clickhouse"]
env = { CLICKHOUSE_URL = "http://localhost:8123", CLICKHOUSE_USER = "default", CLICKHOUSE_MODE = "read-only" }

VS Code（GitHub Copilot、エージェントモード） — .vscode/mcp.json に記述します：

{
  "servers": {
    "clickhouse": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@dockndevai/mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_URL": "http://localhost:8123",
        "CLICKHOUSE_USER": "default",
        "CLICKHOUSE_MODE": "read-only"
      }
    }
  }
}

プロンプトの例

• 「analytics データベースで最も大きなテーブルは何ですか？」
• 「events のスキーマを表示して、今週の日次件数をクエリしてください。」
• 「現在実行中で、最も多くのメモリを使用しているクエリはどれですか？」

ソースから実行する（開発）

上記の公開パッケージを推奨します。クローンから実行する場合：

npm install
npm run build
node dist/index.js   # with the environment variables set

開発

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