beget-s3-mcp-ai-cli

Beget S3 MCP サーバー＆AI CLI

Beget S3 用の MCP サーバーと CLI です。既存のバケットを Claude Code、Cursor、Codex に接続して、ファイルを確認したり、バックアップを復元したりできます。バイナリ beget-s3 は、管理パネルで利用できる機能と、S3 プロファイルの保守的な制限を考慮しています。

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

英語版

Beget S3 Object Storage 用の Go 製 MCP サーバー、CLI、エージェントスキルです。Claude Code、Cursor、Codex を、アクセス範囲を限定したオブジェクトストレージに接続し、内容の確認やバックアップの復元に利用できます。バケットと共有リンクはコンソールで操作します。署名付き URL とバケット API は無効です。英語版の完全なガイドをご覧ください。

クイックスタート

Releases からお使いのプラットフォーム用バイナリをダウンロードするか（v0.1.0 は公開済みで、MCP Registry と Smithery にも掲載されています）、Go 1.27.2 でビルドしてください。

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

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

優先順位は、フラグ > env > ファイルです。環境変数：BEGET_S3_ACCESS_KEY_ID、BEGET_S3_SECRET_ACCESS_KEY、BEGET_S3_POOL（ru1）、BEGET_S3_ENDPOINT。HTTP を使うには BEGET_S3_ALLOW_INSECURE=1 が必要です。

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

機能

まず Beget の管理パネルでバケットを作成してください。S3 API による作成・削除とバケット設定の読み取りは無効です。CORS と公開ポリシーは管理パネルで設定します。Presign MCP ツールは無効です。7 日間の有効期間は管理パネルについて記載されたものであり、外部 SigV4 GET/PUT は確認されていません。大きなファイルには FILE_ROOT を使用してください。API の機能については調査結果をご確認ください。

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

Claude Code、Cursor、Codex への接続

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

{
  "mcpServers": {
    "beget-s3": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "BEGET_S3_ACCESS_KEY_ID",
        "-e",
        "BEGET_S3_SECRET_ACCESS_KEY",
        "-e",
        "BEGET_S3_POOL",
        "ghcr.io/stufently/beget-s3-mcp-ai-cli:0.1.0"
      ],
      "env": {
        "BEGET_S3_ACCESS_KEY_ID": "${env:BEGET_S3_ACCESS_KEY_ID}",
        "BEGET_S3_SECRET_ACCESS_KEY": "${env:BEGET_S3_SECRET_ACCESS_KEY}",
        "BEGET_S3_POOL": "${env:BEGET_S3_POOL}"
      }
    }
  }
}

beget-s3 mcp install --client cursor --dry-run
beget-s3 mcp install --client cursor
beget-s3 mcp install --client claude-desktop
beget-s3 mcp install --client codex
beget-s3 mcp install --client claude-code --scope project
beget-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 が必要です。# >>> beget-s3 (managed) / # <<< beget-s3 (managed) の間のブロックだけが置き換えられます。マーカーのないテーブルは --force を指定しても置き換えられません。それ以外の TOML のバイト列は変更されません。

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

MCP ツール

Level	Tools
read	s3_list_buckets, s3_list_objects, s3_head_object, s3_get_object, s3_preview_object, s3_list_multipart_uploads, s3_list_parts, s3_largest_objects, s3_prefix_usage, s3_unfinished_uploads
read + FILE_ROOT	s3_download_file
write	s3_put_object, s3_create_folder, s3_copy_object, s3_multipart_create, s3_multipart_complete
write + FILE_ROOT	s3_upload_file
delete	s3_delete_object, s3_delete_objects, s3_multipart_abort

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

一覧は continuation_token を使って最大 1000 件を取得します。バージョン／マルチパートには 2 つ目のマーカーがあります。インライン get/put は 262144 バイト、preview は 65536 バイトまでです。大きなファイルは FILE_ROOT／マルチパート経由で処理されます。このプロファイルでは presign は無効です。応答には structuredContent と JSON テキストが含まれます。テキストが 256 KiB を超える場合は、簡潔な概要に置き換えられます。エラーには code/message/retryable が含まれます。429/503 の場合、SDK が適応的に再試行します。

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

シナリオ：既存のバケットからファイルを確認して復元する

Beget のパネルでバケットを作成し、そのアクセスキーを使用します。バックアップの確認には、オブジェクト一覧、メタデータ、ダウンロードだけで十分です。このプロファイルでバケットや presigned リンクを作成する必要はありません。

beget-s3 ls backups/daily/ --json
beget-s3 stat backups/daily/archive.tar
beget-s3 cp s3://backups/daily/archive.tar ./restored-beget.tar

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

CLI

beget-s3 cp ./archive.tar s3://backups/daily/archive.tar --part-size 5242880 --overwrite --yes
beget-s3 ls backups/daily/ --max-keys 100 --json
beget-s3 stat backups/daily/archive.tar
beget-s3 cp s3://backups/daily/archive.tar ./restored.tar
beget-s3 cp ./directory s3://backups/tree/ --recursive --overwrite --yes
beget-s3 cp s3://backups/tree/ ./restored-directory --recursive
beget-s3 cp s3://backups/daily/archive.tar s3://backups/copy.tar --overwrite --yes
beget-s3 cat backups/daily/notes.txt
beget-s3 du backups/daily/ --max-scan 10000 --json
beget-s3 rm backups/moved.tar --yes
beget-s3 doctor --json
beget-s3 compat --markdown

cp は通常のローカルパスと、S3 URI s3://bucket/key または beget-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 エージェント向けスキル

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

デフォルトでは ~/.claude/skills/beget-s3 にインストールします。SKILL.md と 6 つのリファレンス（バックアップ／復元、共有、最小権限、コスト管理、移行、インシデント対応）を冪等にインストールします。トリガー：「beget s3」、「Beget バケット」、「s3 にアップロード」、「presigned」、「s3 にバックアップ」。

セキュリティ

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

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

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

スコープ：BEGET_S3_ALLOWED_BUCKETS=backups および BEGET_S3_ALLOWED_PREFIXES=backups/daily/。プレフィックスはセグメント境界を考慮するため、daily-evil は対象になりません。'..' セグメントは拒否されます。部分的なスコープでは、ALLOWED_BUCKETS に含まれていても、バケット全体や広範囲のリスト操作は禁止されます。Copy/move では、ソースと対象の両方を確認します。

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

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

Beget のプールとストレージクラス

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

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

FAQ

Beget のバケットは、mb コマンドまたは MCP で作成できますか？ いいえ。bucket_create、bucket_delete、bucket_config は無効になっています。Beget のパネルでバケットを作成してください。互換性テーブルに、現在のプロファイルの制限が記載されています。

CLI と MCP で Beget の presigned リンクが使えないのはなぜですか？ 外部 SigV4 presign は確認されていないため、presign=false です。パネルのリンクについてはBeget の調査をご覧ください。これは外部 GET/PUT リンクがサポートされることを保証するものではありません。

CLI で Beget S3 からバックアップをダウンロードするにはどうすればよいですか？ beget-s3 auth set を実行した後、stat bucket/key を実行し、続いて cp s3://bucket/key ./new-file を実行します。MCP でダウンロードする場合は、ローカルパスを制限する BEGET_S3_FILE_ROOT も設定してください。

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 をご覧ください。ツールはプロファイルに応じて登録されます。このバージョンでは、ライフサイクル、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、Beget のドキュメントが残ります。