Claude CodeにZilliz Cloudプラグインを入れてMilvusを操作する

Zilliz Cloudのプラグインを入れると、Claude Codeがzilliz-cli(Zilliz Cloud用のコマンドラインツール)を代わりに叩き、Milvusクラスターの作成からベクトル検索、権限設定、バックアップまでを自然文の指示で進められます。コンソールを開いたり、CLIのサブコマンドを覚えたりする必要はありません。

ただし相手は課金される本番クラスターです。この記事ではインストールと認証の手順に加えて、クラスター削除のような取り消せない操作をClaude Codeに任せきりにしない設定まで書きます。

何が入るのか: コマンド2つとスキル群

プラグイン名は zilliz、マーケットプレイス名は zilliztech です。リポジトリはZilliz公式で、Claude Code用とOpenAI Codex用の2形式を1つのskillsディレクトリで共有しています。

Claude Codeで使えるスラッシュコマンドは2つだけです。

残りの操作はスキルとして用意されています。Claudeが依頼文から必要なスキルを選び、中でzilliz-cliのコマンドを実行する形です。

スキルの数が3通りに見える理由

導入前に気づきやすい点があります。スキルの数が見た場所によって違います。

• マーケットプレイスの掲載ページの説明は「14 skills」
• READMEのスキル表は20行
• リポジトリのskillsディレクトリには22個のフォルダ

READMEの表に載っていない2つは diagnose と ask-zilliz です。diagnose はクラスターやコレクションの不調を読み取り専用で診断するスキルで、実行するのは既存の zilliz コマンドだけ、提案は「次に打つコマンド」として示す作りです。ask-zilliz はプラン選びや料金見積もり、SDKの使い方に答える案内役です。

掲載ページの数字とリポジトリの中身は一致していません。実際に何が入るかは、インストール後に /plugin のパネルで確かめるのが確実です。

始める前に必要なもの

READMEのRequirementsに書かれている前提は、Zilliz Cloudのアカウント(またはローカルのMilvus)の1行だけです。ローカルのMilvusでどのスキルが動くかは、READMEに記載がありません。この記事の手順とコマンド例は、Zilliz Cloudのクラスターを相手にした流れで書いています。

もう1つの前提は、Claude Codeのプラグイン機能です。zilliz-cliは自分で入れなくても、次の節の /zilliz:quickstart がinstall.shで導入します。

インストールから最初の接続まで

コマンドをまとめて示します。

/plugin marketplace add zilliztech/zilliz-plugin
/plugin install zilliz@zilliztech
/zilliz:quickstart

@ の右側はリポジトリのパスではなくマーケットプレイス名です。zilliz@zilliztech/zilliz-plugin と書くと解決できません。マーケットプレイスの追加と導入を別々にする理由や、URLで配る場合の注意はプラグインマーケットプレイスをURLで配る落とし穴にあります。

quickstartが実際にやること

スキルの手順は5段階です。

1. zilliz --version で導入済みか確認し、無ければ公式のinstall.shを実行する
2. zilliz auth status でログイン状態を確認する
3. 未ログインならユーザーに認証を頼む
4. zilliz cluster list でクラスターを選ぶ(無ければ zilliz cluster create --type serverless で作成を提案する)
5. zilliz context set --cluster-id <id> で操作対象を固定し、zilliz context current と zilliz collection list で動作を確かめる

3番目が重要です。認証コマンドは対話入力が必要でエージェント内では動かないため、スキルは「自分のターミナルで実行してください」とユーザーに頼む作りになっています。ログイン方法は次の4つです。

• zilliz login: ブラウザでOAuth。推奨で、全機能が使える
• zilliz login --api-key: APIキーを対話入力
• zilliz configure: APIキーを入力する旧来の方式
• 環境変数 ZILLIZ_API_KEY を .zshrc などに書く

APIキーをチャットに貼らないよう、スキル自身が明記しています。キーを会話に載せるとトランスクリプトに残るので、この指示は守る価値があります。

更新するとき

/plugin marketplace add は追加済みのマーケットプレイスを更新せず、/plugin install も導入済みなら何もしません。新しい版を取り込むには次の2行が必要です。

/plugin marketplace update zilliztech
/plugin update zilliz@zilliztech

導入後にコンテキストへどれだけ上乗せされるかは、シェルで claude plugin details zilliz を実行すると見積もれます。読み方はclaude plugin detailsの解説にまとめています。スキルが20個を超えるので、一度測っておくと判断しやすくなります。

自然文で任せられる作業の例

READMEには、次のような依頼文が例として並んでいます。

• us-east-1にサーバーレスクラスターを作り、768次元のベクトルを持つコレクションを用意する
• 商品コレクションから、age > 20 の条件付きで類似アイテムを検索する
• 本番クラスターに、保持7日の日次バックアップポリシーを設定する
• 分析用コレクションに読み取り専用のロールを作る
• 今月の使用量と請求書を表示する

裏で実行されるコマンドは、スキルの定義で確認できます。たとえばベクトル検索は次の形です。

zilliz vector search --collection products \
  --data '[[0.1, 0.2, 0.3]]' \
  --limit 5 \
  --filter 'age > 20' \
  --output-fields '["id", "text"]'

--data に渡すのはベクトルそのものです。文章を渡しても意味検索にはならず、先に埋め込みモデルでベクトル化する必要があります。次元数もコレクションの定義と完全に一致させます。スキルは、検索前に zilliz collection describe でスキーマを見るよう促す作りです。

ハイブリッド検索は zilliz vector hybrid-search で、--rerank '{"strategy": "rrf", "params": {"k": 60}}' のようにRRFを指定できます。

Vector Lakeとオンデマンドクラスターも操作できる

READMEの例には、Vector Lakeを作り、アイドル時の自動停止を30分にしたオンデマンドクラスターを立ち上げる依頼も含まれています。スキル側の定義では、Vector Lakeは保存層で、検索などの処理はそこへ接続するオンデマンドクラスターが担います。

作成には専用のサブコマンドを使い、通常のクラスターのように --type は渡しません。

zilliz cluster create-vectorlake \
  --project-id <project-id> \
  --region-id <region-id> \
  --session-ttl 30m

--session-ttl はアイドル時に自動停止するまでの時間で、下限は60秒です。

取り消せない操作を止める設定

スキルの指示文には「クラスターを削除する前に必ずユーザーに確認する。取り消せない」「バックアップ削除の前に確認する」と書かれています。ただしこれはClaudeへの指示であり、強制力はありません。確実に止めたいなら、Claude Code側の権限設定で縛ります。

.claude/settings.json に次のように書くと、削除系は確認付き、禁止したいものは実行不可になります。

{
  "permissions": {
    "allow": [
      "Bash(zilliz cluster list *)",
      "Bash(zilliz cluster describe *)",
      "Bash(zilliz collection list *)",
      "Bash(zilliz collection describe *)",
      "Bash(zilliz context current *)",
      "Bash(zilliz auth status *)",
      "Bash(zilliz billing usage *)"
    ],
    "ask": [
      "Bash(zilliz cluster suspend *)",
      "Bash(zilliz cluster modify *)",
      "Bash(zilliz vector delete *)"
    ],
    "deny": [
      "Bash(zilliz cluster delete *)",
      "Bash(zilliz backup delete *)"
    ]
  }
}

広いdenyに合致する呼び出しは、より狭いallowがあっても止まります。askも同様で、合致すればallowがあっても確認が出ます。上の例で参照系を allow に置いても、削除系が巻き込まれることはありません。

* はサブコマンドの後ろに置いてください。Bash(zilliz * delete) のように手前へ置くと、起動時に警告が出ます。この例の * はすべて末尾にあるので、警告は出ません。

この例は読み取りを許可し、変更を確認付きにし、削除を禁止する分け方の一例です。サブコマンド名は上のスキル定義に載っているものを使っているので、運用に合わせて増減してください。

CLAUDE.mdに書いておくと事故が減る規約

権限設定が「してはいけない」を担うなら、CLAUDE.mdは「どこで作業するか」を担います。たとえば次のような断片を置くと、Claudeが本番クラスターを触る確率を下げられます。

## Zilliz Cloud
- 作業対象のクラスターは `dev-vectors` のみ。`zilliz context current` で確認してから操作する
- 本番クラスターでは参照系(list / describe / search)だけを実行する
- クラスターの作成は serverless か free のみ。dedicated は事前に相談する
- 検索や挿入の前に `zilliz collection describe` でスキーマと次元数を確認する
- `zilliz billing usage` で使用量を見てから、クラスターのサイズ変更を提案する

これはチームで決める運用規則の例で、プラグインの機能ではありません。専用クラスターを開発用と本番用に分け、文脈(zilliz context set)の確認を最初の一手に固定するという考え方です。

つまずきやすい点

もう一点、バックアップの作成・エクスポート・復元も非同期です。開始した後は backup describe で進み具合を見ます。復元は、クラスター全体なら新しいクラスターとして、コレクション単位なら既存クラスターの中へ戻る点が違います。

まとめ

導入は /plugin marketplace add と /plugin install の2コマンドと、/zilliz:quickstart で終わります。難所はインストールではなく、課金と削除の両方を伴う操作をどこまで自動で通すかの線引きです。参照系をallow、変更系をask、削除系をdenyに分け、作業するクラスターをCLAUDE.mdで固定する、という3点を先に決めておくと安全に任せられます。

プラグインを自作して同じような操作を包みたい場合は、mcp-server-devプラグインでMCPサーバーを作るが参考になります。