yandex-s3-mcp-ai-cli

Yandex Cloud S3 MCP サーバー＆AI CLI

Yandex Cloud の S3（Yandex Cloud Object Storage）向け MCP サーバーと CLI です。Claude Code、Cursor、Codex から、ファイルの検索、バージョンの確認、バックアップの復元を行えます。バイナリ yandex-s3 には、MCP、コマンドライン、エージェントスキルが統合されています。

英語版ガイド · S3 MCP サーバーのディレクトリ

English

Yandex Cloud S3 Object Storage 向けの Go 製 MCP サーバー、CLI、エージェントスキルです。Claude Code、Cursor、Codex を、スコープを限定したオブジェクトストレージに接続して、確認やバックアップの復元を行えます。ru-central1。上書きしない書き込みにはプロファイルの制限が適用されます。英語版の完全なガイドをご覧ください。

クイックスタート

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

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

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

優先順位：フラグ > env > ファイル。環境変数：YANDEX_S3_ACCESS_KEY_ID、YANDEX_S3_SECRET_ACCESS_KEY、YANDEX_S3_POOL（ru-central1）、YANDEX_S3_ENDPOINT。HTTP を使用するには YANDEX_S3_ALLOW_INSECURE=1 が必要です。

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

機能

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

Claude Code、Cursor、Codex への接続

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

{
  "mcpServers": {
    "yandex-s3": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "YANDEX_S3_ACCESS_KEY_ID",
        "-e",
        "YANDEX_S3_SECRET_ACCESS_KEY",
        "-e",
        "YANDEX_S3_POOL",
        "ghcr.io/stufently/yandex-s3-mcp-ai-cli:0.1.0"
      ],
      "env": {
        "YANDEX_S3_ACCESS_KEY_ID": "${env:YANDEX_S3_ACCESS_KEY_ID}",
        "YANDEX_S3_SECRET_ACCESS_KEY": "${env:YANDEX_S3_SECRET_ACCESS_KEY}",
        "YANDEX_S3_POOL": "${env:YANDEX_S3_POOL}"
      }
    }
  }
}

yandex-s3 mcp install --client cursor --dry-run
yandex-s3 mcp install --client cursor
yandex-s3 mcp install --client claude-desktop
yandex-s3 mcp install --client codex
yandex-s3 mcp install --client claude-code --scope project
yandex-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 が必要です。置き換えられるのは # >>> yandex-s3 (managed) と # <<< yandex-s3 (managed) の間のブロックのみです。マーカーのないテーブルは --force を指定しても置き換えられず、TOML のその他のバイトはそのまま保持されます。

権限レベルは個別に有効化できます：yandex-s3 mcp --allow-write --allow-delete --allow-admin または YANDEX_S3_ALLOW=write,delete,admin。フラグは mcp install でも使用できます。FILE_ROOT は YANDEX_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

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

リストの上限は1000項目で、continuation_tokenを使います。バージョンとマルチパートには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を使って集計結果のページを返します。これは課金情報ではありません。

シナリオ：オブジェクトのインベントリ作成とバックアップのバージョン確認

復元する前に、Yandex Object Storageのプレフィックスの内容とオブジェクトのバージョンを確認してください。バージョニングが有効なバケットではversionsコマンドが便利です。以下のcpは現在のバージョンをダウンロードします。

yandex-s3 ls backups/daily/ --json
yandex-s3 versions backups/daily/ --json
yandex-s3 cp s3://backups/daily/archive.tar ./restored-yandex.tar

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

CLI

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

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

doctorは認証情報のソースと権限、DNS/TLS、DateとListBucketsによる時計のずれを確認します。5分を超えると警告、15分を超えるとエラーになります。

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

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

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

YANDEX_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 には同じゲートが必要です。

スコープ：YANDEX_S3_ALLOWED_BUCKETS=backups および YANDEX_S3_ALLOWED_PREFIXES=backups/daily/。プレフィックスはセグメント境界を考慮するため、daily-evil は一致しません。「..」セグメントは拒否されます。部分的なスコープでは、ALLOWED_BUCKETS に含まれていても、バケット全体と広範囲の一覧表示は禁止されます。Copy／move ではソースと対象の両方を検証します。

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

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

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

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

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

よくある質問

Yandex Object Storage を Claude Code に接続するにはどうすればよいですか？ yandex-s3 をビルドし、auth set で S3 キーを保存して、mcp install --client claude-code --scope project を実行します。MCP は読み取り専用アクセスで起動します。キーはクライアントの設定には書き込まれません。

上書きせずに Yandex S3 へアップロードできないのはなぜですか？ プロファイルでは conditional_writes=false となっています。すべての書き込みパスで条件付き書き込みが保証されることは、まだ確認されていません。自動化のために拒否を回避しないでください。詳細と実環境での確認予定については、調査資料をご覧ください。

Yandex S3 のファイルへのリンクを発行できますか？ yandex-s3 presign backups/daily/archive.tar --expires 3600 で一時的な GET リンクを作成できます。リンクは秘密情報として扱ってください。最大有効期間とサービスの実際の動作については、まだ実環境での確認が必要です。

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、Yandex Cloud のドキュメントが残ります。