vkcloud-s3-mcp-ai-cli

VK Cloud S3 MCP Server & AI CLI

VK Cloud（VK Cloud）の S3 向け MCP サーバーと CLI です。Hotbox/Icebox を Claude Code、Cursor、Codex に接続し、オブジェクトを参照したり、バックアップをダウンロードしたりできます。バイナリ vkcloud-s3 は、クラウドの機能に対応した専用プロファイルを使用します。

英語ガイド · S3 MCP サーバーのカタログ

英語

VK Cloud S3 Object Storage 向けの Go 製 MCP サーバー、CLI、エージェントスキルです。Claude Code、Cursor、Codex を、スコープが限定されたオブジェクトストレージに接続して、内容の確認やバックアップの復元を行えます。ru-msk と kz-at のプールに対応しています。バケットタグ付けは無効です。英語版の完全なガイドをご覧ください。

クイックスタート

使用するプラットフォームのバイナリを Releases から入手するか（v0.1.0 を公開済み。MCP Registry と Smithery にも登録済み）、Go 1.27.2 でビルドします。

bash scripts/go.sh go build -o vkcloud-s3 ./cmd/vkcloud-s3
./vkcloud-s3 version
./vkcloud-s3 auth set
./vkcloud-s3 auth status
./vkcloud-s3 ls --json

auth set は key ID と secret の入力を求め、入力内容を表示しません。TTY がない場合は、stdin から2行を読み込みます。シークレットを argv に渡さないでください。ファイル ~/.config/vkcloud-s3/credentials は 0600 でアトミックに作成され、それより広い権限は拒否されます。

優先順位は、フラグ > env > ファイルです。環境変数：VKCLOUD_S3_ACCESS_KEY_ID、VKCLOUD_S3_SECRET_ACCESS_KEY、VKCLOUD_S3_POOL（ru-msk）、VKCLOUD_S3_ENDPOINT。HTTP を使用するには VKCLOUD_S3_ALLOW_INSECURE=1 が必要です。

イメージ：ghcr.io/stufently/vkcloud-s3-mcp-ai-cli:0.1.0。ローカルでのビルド：docker build -t vkcloud-s3 . イメージは uid 65532 で MCP を実行し、CA 証明書を含みます。認証情報はプライベートな環境またはファイル経由で渡してください。

機能

• プロファイルの範囲内で、ストリーミングによる object CRUD、copy、multipart、presigned URL に対応します。
• バージョン、タグ、CORS、ポリシー、Object Lock configuration は、サポートされている場合に登録されます。
• 制限付きスキャン、診断、JSON、MCP と組み込みスキルのインストールに対応します。

Claude Code、Cursor、Codex への接続

このボタンを使うと、Docker イメージ ghcr.io/stufently/vkcloud-s3-mcp-ai-cli:0.1.0 から、読み取り専用モードで MCP がインストールされます。キーは設定に書き込まれません。Cursor は環境変数から ${env:…} を参照するため、Cursor の起動元となる環境で VKCLOUD_S3_ACCESS_KEY_ID と VKCLOUD_S3_SECRET_ACCESS_KEY を設定してください。バケットがデフォルトのプールにない場合は VKCLOUD_S3_POOL も設定します（空の値はデフォルトのプールを意味します）。同じブロックを Windsurf（mcp_config.json）と、手動での ~/.cursor/mcp.json にも使用できます。

{
  "mcpServers": {
    "vkcloud-s3": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "VKCLOUD_S3_ACCESS_KEY_ID",
        "-e",
        "VKCLOUD_S3_SECRET_ACCESS_KEY",
        "-e",
        "VKCLOUD_S3_POOL",
        "ghcr.io/stufently/vkcloud-s3-mcp-ai-cli:0.1.0"
      ],
      "env": {
        "VKCLOUD_S3_ACCESS_KEY_ID": "${env:VKCLOUD_S3_ACCESS_KEY_ID}",
        "VKCLOUD_S3_SECRET_ACCESS_KEY": "${env:VKCLOUD_S3_SECRET_ACCESS_KEY}",
        "VKCLOUD_S3_POOL": "${env:VKCLOUD_S3_POOL}"
      }
    }
  }
}

vkcloud-s3 mcp install --client cursor --dry-run
vkcloud-s3 mcp install --client cursor
vkcloud-s3 mcp install --client claude-desktop
vkcloud-s3 mcp install --client codex
vkcloud-s3 mcp install --client claude-code --scope project
vkcloud-s3 mcp install --client claude-code --scope user

最後のコマンドは claude mcp add を表示するだけです。バイナリのパスは絶対パスで、キーは設定に書き込まれません。Cursor：~/.cursor/mcp.json、Claude Code project：./.mcp.json、Desktop：使用する OS の設定ディレクトリです。JSON の更新では、既存のキーを保持し、.bak の作成と冪等性を確保します。

Codex：~/.codex/config.toml。既存のテーブルを変更するには --force が必要です。# >>> vkcloud-s3 (managed) / # <<< vkcloud-s3 (managed) の間のブロックだけが置き換えられます。マーカーのないテーブルは、--force を指定しても置き換えられません。TOML のその他のバイト列はそのまま保持されます。

各レベルは個別に有効化できます：vkcloud-s3 mcp --allow-write --allow-delete --allow-admin または VKCLOUD_S3_ALLOW=write,delete,admin。フラグは mcp install でも使用できます。FILE_ROOT は VKCLOUD_S3_FILE_ROOT で有効化します。

MCP ツール

Level	Tools
read	s3_list_buckets, s3_list_objects, s3_head_object, s3_get_object, s3_preview_object, s3_presign_get, s3_list_object_versions, s3_list_multipart_uploads, s3_list_parts, s3_get_bucket_config, s3_largest_objects, s3_prefix_usage, s3_unfinished_uploads, s3_get_object_tagging
read + FILE_ROOT	s3_download_file
write	s3_put_object, s3_create_folder, s3_copy_object, s3_presign_put, s3_multipart_create, s3_multipart_presign_part, s3_multipart_complete, s3_put_object_tagging
write + FILE_ROOT	s3_upload_file
delete	s3_delete_object, s3_delete_objects, s3_multipart_abort
admin	s3_create_bucket, s3_put_bucket_versioning, s3_put_bucket_cors, s3_put_bucket_policy, s3_delete_bucket_policy, s3_put_object_lock_configuration
admin + delete	s3_delete_bucket

リソース：vkcloud-s3://config、vkcloud-s3://capabilities、vkcloud-s3://pools。サポートされていない機能に対応するツールは除外されます。

リストは continuation_token を使い、最大1000件まで取得できます。バージョン／マルチパートには2つ目のマーカーがあります。インラインの get／put は262144バイト、プレビューは65536バイトまでです。大きなファイルは presigned URL または FILE_ROOT 経由で処理します。レスポンスには structuredContent と JSON テキストが含まれます。256 KiB を超えるテキストは簡潔な概要に置き換えられます。エラーには code/message/retryable が含まれます。429／503 では SDK が適応的に再試行します。

分析では最大 max_scan 件（デフォルトは10000件）をスキャンします。partial/token は結果が不完全であることを示します。Prefix usage は next_result_offset を使って集計結果のページを返します。これは請求情報ではありません。

シナリオ：Hotbox／Icebox の確認と必要なリージョンへのアクセス

プロファイルにはモスクワの ru-msk プールとカザフスタンの kz-ast プールが含まれます。バケットのプールを選び、Hotbox／Icebox のメタデータを確認して、既存のアーカイブを共有するための短縮リンクを作成します。

vkcloud-s3 --pool ru-msk stat backups/daily/archive.tar
vkcloud-s3 --pool ru-msk du backups/daily/ --max-scan 10000 --json
vkcloud-s3 --pool ru-msk presign backups/daily/archive.tar --expires 3600

例では既存のバケット backups とオブジェクト daily/archive.tar を使用しています。ご自身の値に置き換えてください。プロファイルとクラウド API は、まだ実環境での確認が必要です。

CLI

vkcloud-s3 mb backups
vkcloud-s3 cp ./archive.tar s3://backups/daily/archive.tar --part-size 5242880 --overwrite --yes
vkcloud-s3 ls backups/daily/ --max-keys 100 --json
vkcloud-s3 stat backups/daily/archive.tar
vkcloud-s3 cp s3://backups/daily/archive.tar ./restored.tar
vkcloud-s3 cp ./directory s3://backups/tree/ --recursive --overwrite --yes
vkcloud-s3 cp s3://backups/tree/ ./restored-directory --recursive
vkcloud-s3 cp s3://backups/daily/archive.tar s3://backups/copy.tar --overwrite --yes
vkcloud-s3 cat backups/daily/notes.txt
vkcloud-s3 versions backups/daily/ --json
vkcloud-s3 du backups/daily/ --max-scan 10000 --json
vkcloud-s3 presign backups/daily/archive.tar --expires 3600
vkcloud-s3 rm backups/copy.tar --yes
vkcloud-s3 rb empty-bucket --yes
vkcloud-s3 doctor --json
vkcloud-s3 compat --markdown

cp は通常のローカルパスと S3 URI s3://bucket/key または vkcloud-s3://bucket/key を受け付けます。大容量アップロードには manager／multipart を使用し、--recursive はディレクトリ／プレフィックスをコピーします。上書きには --overwrite と確認が必要です。ダウンロードはアトミックに行われます。rm/rb/mv は、TTY 以外では --yes を指定しないとコード2を返し、TTY では確認を求めます。--json は共通で、エラーは stderr に出力され、終了コードはゼロ以外になります。

doctor は認証情報のソース／権限、DNS／TLS、Date による時刻、ListBuckets を確認します。5分超は警告、15分超はエラーです。

AI エージェント向けスキル

vkcloud-s3 skill install
vkcloud-s3 skill install --target ./agent-skills/vkcloud-s3

デフォルトのインストール先は ~/.claude/skills/vkcloud-s3 です。SKILL.md と6つの references（backup/restore、share、least privilege、cost hygiene、migration、incident response）を冪等にインストールします。トリガー：「vkcloud s3」、「VK Cloud バケット」、「s3 にアップロード」、「presigned」、「s3 にバックアップ」。

セキュリティ

conditional_writes:false の場合、上書きなしの書き込みは S3 リクエストを送信する前に拒否されます。HEAD ではアトミックな保護を実現できません。一貫性のある書き込みを行うには、確認ポリシーを維持したうえで、CLI では --overwrite --yes、MCP では overwrite:true, confirm:true を使用してください。conditional_delete:false の場合、mv と s3_move_object は無効になります。

MCP ではデフォルトで read のみが登録されます。サポートされていない機能や、必要な権限レベルが不足している場合、そのツールは除外されます。

VKCLOUD_S3_DESTRUCTIVE_POLICY：confirm はクライアントが対応していれば elicitation を使用します。対応していない場合は、人間の同意を得たうえで confirm:true が必要です。elicit は elicitation を必須とし、confirm:true による回避はできません。block は常に禁止し、allow はゲートなしで実行します。拒否は、S3 リクエストを送信する前に行われます。このゲートは、削除、move、presigned PUT、ポリシー/Object Lock、versioning の停止、上書きを対象とします。

conditional_writes:true の場合、put/copy/move/multipart complete/upload file 操作では overwrite:false、宛先への HEAD、If-None-Match: * を使用します。false の場合、デフォルトで書き込みは拒否されます。overwrite:true には同じゲートが適用されます。

スコープ：VKCLOUD_S3_ALLOWED_BUCKETS=backups と VKCLOUD_S3_ALLOWED_PREFIXES=backups/daily/。プレフィックスはセグメント境界を考慮するため、daily-evil は一致しません。「..」セグメントは拒否されます。部分的なスコープが設定されている場合、そのバケットが ALLOWED_BUCKETS に含まれていても、バケット全体への操作と広範なリスト取得は禁止されます。Copy/move では、ソースと宛先の両方を検証します。

ファイル関連の MCP ツールは os.Root を使用します。FILE_ROOT 内の相対パスのみが許可され、「..」、絶対パス、外部を指すシンボリックリンクは拒否されます。呼び出しごとに stderr へ JSON を 1 行出力します。VKCLOUD_S3_AUDIT_FILE を設定すると、0600 で追加出力します。シークレットと X-Amz-Signature/Credential/Security-Token はログおよびエラー内でマスキングされます。完全な署名付き URL は操作結果としてのみ返されます。S3 キー自体の権限も制限してください。

s3_download_file はデフォルトで、ダウンロードしたファイルを既存ファイル（ダウンロード中に作成されたファイルも含む）を置き換えずに公開します。置き換えるには overwrite:true を渡してください。確認フォーム、または人間の同意を得た後の confirm:true によって、破壊的操作ポリシーが適用されます。

VK Cloud のプールとストレージクラス

プール、エンドポイント、クラスについては互換性テーブルを参照してください。各項目、価格、エラーの一次情報については調査資料を参照してください。デフォルトのプールは ru-msk です。SigV4 のリージョンは選択したプールと同じです。プロファイルの verified:false は、versitygw での検証ではクラウドの API を確認できないことを示します。確認されていない情報には [推定] のマークが付いています。プロファイル内の価格は請求額の計算には使用できません。

Lifecycle、ACL、バケットタグ付け、オブジェクト保持はクラウドでサポートされている場合がありますが、このバージョンでは設定用のツールを提供していません。プロファイルの情報は、S3 API との互換性を示しています。

よくある質問

VK Cloud S3 のエンドポイントはどのように選べばよいですか？ VKCLOUD_S3_POOL=ru-msk または kz-ast を使用してください。対応するエンドポイントは互換性プロファイルから取得されます。選択したサービスとは無関係に、署名リージョンを変更しないでください。

このプロジェクトは Hotbox と Icebox に対応していますか？ どちらのクラスも、プロファイルでは STANDARD と STANDARD_IA として表されています。クラスがプロファイルに含まれていても、CLI がオブジェクトをクラス間で自動的に移行するわけではありません。詳細と料金については、VK Cloud の調査資料をご覧ください。

MCP 経由で VK Cloud のバケットタグを変更できますか？ bucket_tagging は無効になっています。オブジェクトタグ用ツールとバケットタグ用ツールは、互換性があるものとして扱わないでください。vkcloud-s3://capabilities と以下のツール一覧を確認してください。

MCP サーバーとは何ですか？ MCP サーバーは、Model Context Protocol を介してエージェントにツールとリソースを提供するプログラムです。ここでは stdio を使用します。

MCP サーバーを Claude Code に接続するにはどうすればよいですか？ auth set のキーを保存してから、project install または表示された user コマンドを使用してください。

エージェントに S3 へのアクセスを許可しても安全ですか？ キー、スコープ、権限レベルを制限してください。confirm/block を維持し、破壊的な影響を伴う操作は内容を理解したうえで承認してください。

aws-cli や rclone とは何が違いますか？ バイナリには MCP、ゲート、監査、分析、スキル、CLI が統合されています。aws-cli/rclone は引き続き、単独の転送／自動化ツールとして使用できます。

どの機能に対応していますか？ capabilities と compat をご覧ください。ツールはプロファイルに応じて登録されます。このバージョンでは、lifecycle、ACL、bucket tagging、object retention は設定できません。

その他のプロバイダー

共通カタログ：ロシア向け S3 の MCP サーバーと CLI。

プロバイダー	リポジトリ	シナリオ
Selectel	selectel-s3-mcp-ai-cli	プールの選択とバックアップの復元
Yandex Cloud	yandex-s3-mcp-ai-cli	オブジェクトのインベントリ作成とバックアップのバージョン確認
VK Cloud	vkcloud-s3-mcp-ai-cli	Hotbox/Icebox の確認と適切なリージョンへのアクセス
Cloud.ru	cloudru-s3-mcp-ai-cli	Evolution Object Storage へのアクセス診断
Timeweb Cloud	timeweb-s3-mcp-ai-cli	アーカイブの復元とプレフィックスの容量管理
MWS	mws-s3-mcp-ai-cli	HMAC アクセスの確認とアーカイブへの短縮リンク
Beget	beget-s3-mcp-ai-cli	準備済みバケット内のファイルの表示と復元
Shared Go kit	s3-mcp-ai-cli-kit	共通の MCP、CLI、保護機能、CI

ライセンス

MIT。検証済みの事実と推測。

Docker でのチェック：bash scripts/go.sh go test -race ./..., bash scripts/conformance.sh, bash scripts/mcp_smoke.sh, bash scripts/mutation_gate.sh, bash scripts/check_docs.sh。Conformance では versitygw v1.8.0 とテスト用キーを使用します。

共通の MCP/CLI、保護機能、チェックは s3-mcp-ai-cli-kit v0.1.0 が提供します。このリポジトリには、組み込みプロファイル、薄い main、VK Cloud のドキュメントが残されています。