cloudru-s3-mcp-ai-cli

Cloud.ru S3 MCP サーバー＆AI CLI

Cloud.ru Evolution Object Storage 用の MCP サーバーと CLI です。S3 ストレージを Claude Code、Cursor、Codex に接続し、アクセスを診断してファイルを復元できます。バイナリ cloudru-s3 は、エンドポイント s3.cloud.ru の Evolution を対象としています。

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

英語

Cloud.ru S3 Object Storage 用の Go 製 MCP サーバー、CLI、エージェントスキルです。Claude Code、Cursor、Codex を、範囲を限定したオブジェクトストレージに接続し、内容の確認やバックアップからの復元を行えます。Evolution、s3.cloud.ru、ru-central-1 が対象です。Advanced プロファイルには対応していません。英語版の完全なガイドをご覧ください。

クイックスタート

このプロファイルは Evolution Object Storage に接続します。auth set ではキー ID を <tenant_id>:<key_id> の形式で完全に入力します。プールは ru-central-1、エンドポイントは https://s3.cloud.ru です。Advanced OBS には別のプロファイルが必要です。

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

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

auth set はキー ID とシークレットをエコーなしで入力するよう求めます。TTY がない場合は stdin から2行を読み込みます。シークレットを argv に渡さないでください。ファイル ~/.config/cloudru-s3/credentials は 0600 でアトミックに作成されます。これより広い権限は拒否されます。

優先順位は、フラグ > 環境変数 > ファイルです。環境変数：CLOUDRU_S3_ACCESS_KEY_ID、CLOUDRU_S3_SECRET_ACCESS_KEY、CLOUDRU_S3_POOL（ru-central-1）、CLOUDRU_S3_ENDPOINT。HTTP を使用するには CLOUDRU_S3_ALLOW_INSECURE=1 が必要です。

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

機能

• プロファイルの範囲内で、ストリーミングによるオブジェクト CRUD、コピー、マルチパート処理、署名付き URL に対応します。
• バージョン、タグ、CORS、ポリシー、Object Lock 設定は、サポートされている場合に登録されます。
• 範囲を限定したスキャン、診断、JSON、MCP と組み込みスキルのインストールに対応します。

Claude Code、Cursor、Codex への接続

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

{
  "mcpServers": {
    "cloudru-s3": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "CLOUDRU_S3_ACCESS_KEY_ID",
        "-e",
        "CLOUDRU_S3_SECRET_ACCESS_KEY",
        "-e",
        "CLOUDRU_S3_POOL",
        "ghcr.io/stufently/cloudru-s3-mcp-ai-cli:0.1.0"
      ],
      "env": {
        "CLOUDRU_S3_ACCESS_KEY_ID": "${env:CLOUDRU_S3_ACCESS_KEY_ID}",
        "CLOUDRU_S3_SECRET_ACCESS_KEY": "${env:CLOUDRU_S3_SECRET_ACCESS_KEY}",
        "CLOUDRU_S3_POOL": "${env:CLOUDRU_S3_POOL}"
      }
    }
  }
}

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

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

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

権限レベルは個別に有効化できます：cloudru-s3 mcp --allow-write --allow-delete --allow-admin または CLOUDRU_S3_ALLOW=write,delete,admin。フラグは mcp install でも使用できます。FILE_ROOT は CLOUDRU_S3_FILE_ROOT で有効にします。

MCP ツール

レベル	ツール
読み取り	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
読み取り + FILE_ROOT	s3_download_file
書き込み	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
書き込み + FILE_ROOT	s3_upload_file
削除	s3_delete_object, s3_delete_objects, s3_multipart_abort
管理	s3_create_bucket, s3_put_bucket_versioning, s3_put_bucket_cors, s3_put_bucket_policy, s3_delete_bucket_policy, s3_put_object_lock_configuration
管理 + 削除	s3_delete_bucket

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

一覧取得は continuation_token を使って最大 1000 件までです。バージョン／マルチパートでは、2 つ目のマーカーも使用します。インラインの get/put は 262144 バイト、プレビューは 65536 バイトまでです。大きなファイルは presigned URL または FILE_ROOT を使用します。応答には structuredContent と JSON テキストが含まれます。テキストが 256 КиБ を超える場合は、簡潔な要約に置き換えられます。エラーには code/message/retryable が含まれます。429/503 の場合、SDK は適応的に再試行します。

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

シナリオ：Evolution Object Storage のアクセス診断

移行または復元は、Evolution へのアクセスを確認し、プレフィックスを限定的にスキャンするところから始めます。このプロファイルは、エンドポイントとリージョンが異なる Cloud.ru の別の S3 製品には対応していません。

cloudru-s3 doctor --json
cloudru-s3 --pool ru-central-1 ls backups/daily/ --json
cloudru-s3 cp s3://backups/daily/archive.tar ./restored-cloudru.tar

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

CLI

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

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

doctor は、クレデンシャルの出所と権限、DNS/TLS、Date による時刻、および ListBuckets を確認します。5 分を超える差は警告、15 分を超える差はエラーになります。

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

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

デフォルトのインストール先は ~/.claude/skills/cloudru-s3 です。SKILL.md と 6 つのリファレンス（backup/restore、share、least privilege、cost hygiene、migration、incident response）を冪等にインストールします。トリガー：「cloudru s3」、「Cloud.ru バケット」、「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 のみが登録されます。未対応の機能や不足しているレベルがある場合、そのツールは除外されます。

CLOUDRU_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 には同じゲートが適用されます。

スコープ：CLOUDRU_S3_ALLOWED_BUCKETS=backups、CLOUDRU_S3_ALLOWED_PREFIXES=backups/daily/。プレフィックスはセグメント境界を考慮します。daily-evil は一致しません。'..' セグメントは拒否されます。部分的なスコープが設定されている場合、ALLOWED_BUCKETS に含まれていても、バケット全体や広範囲のリスト操作は禁止されます。Copy/move ではソースと書き込み先の両方を検証します。

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

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

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

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

Lifecycle、ACL、bucket tagging、object retention はクラウドでサポートされている場合がありますが、このバージョンでは設定用のツールを提供していません。プロファイルの情報は S3 API との互換性を示すものです。

よくある質問

これは Cloud.ru Evolution 向けですか、それとも Advanced 向けですか？ Evolution Object Storage 向けです。このプロファイルでは https://s3.cloud.ru と ru-central-1 を使用します。これらの値を Advanced に流用しないでください。公式情報と制限事項は Evolution に関するものです。

Cloud.ru S3 のキーとアクセスを確認するにはどうすればよいですか？ cloudru-s3 auth status はローカル設定を確認し、doctor --json はさらにサービスに接続して、DNS/TLS、時刻、ListBuckets を確認します。ネットワークおよびクラウド操作には、有効なご自身のキーが必要です。

SINGLE を Multi-AZ クラスとして扱えますか？ いいえ。このプロファイルでは SINGLE クラスを個別に扱います。プールが Multi-AZ に対応していても、すべてのクラスで冗長性が同じとは限りません。詳細は調査結果に記載されています。

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 と 互換性をご覧ください。ツールはプロファイルに応じて登録されます。このバージョンでは、ライフサイクル、ACL、バケットのタグ付け、オブジェクトの保持設定は行いません。

その他のプロバイダー

総合カタログ：ロシアの 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、Cloud.ru のドキュメントが含まれます。