timeweb-s3-mcp-ai-cli

Timeweb Cloud S3 MCP サーバー＆AI CLI

Timeweb Cloud（タイムウェブ）向けのS3 MCPサーバーとCLIです。Claude Code、Cursor、Codexを通じて、オブジェクトの確認、バックアップ容量の確認、アーカイブのダウンロードができます。バイナリ timeweb-s3 は、コンソールでのバケットプランの選択とは別にS3 APIへ接続します。

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

英語

Timeweb Cloud S3 Object Storage向けのGo製MCPサーバー、CLI、エージェントスキルです。Claude Code、Cursor、Codexを、確認やバックアップ復旧のためのスコープ制限付きオブジェクトストレージに接続します。バケットプランはコンソールで選択します。PUT Object Lock設定は無効です。英語版の完全なガイドをご覧ください。

クイックスタート

cold/premiumの場合はコンソールでバケットを作成してください。mb はデフォルトのクラスを使用します。プロファイルの standard/hot/cold クラスは料金カタログであり、オブジェクトのStorageClassヘッダーではありません。価格が0の場合、GBあたりの料金は不明です。確認が取れるまでPUTによるObject Lock設定は無効です。クラウドのロックについては調査結果をご覧ください。

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

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

auth setでは、キーIDとシークレットを入力します。入力内容は画面に表示されません。TTYがない場合は、stdinから2行を読み取ります。シークレットをargvに渡さないでください。~/.config/timeweb-s3/credentials ファイルはアトミックに作成され、パーミッションは0600に設定されます。これより広いパーミッションは拒否されます。

優先順位：フラグ > env > ファイル。環境変数：TIMEWEB_S3_ACCESS_KEY_ID、TIMEWEB_S3_SECRET_ACCESS_KEY、TIMEWEB_S3_POOL（ru-1）、TIMEWEB_S3_ENDPOINT。HTTPを使用するにはTIMEWEB_S3_ALLOW_INSECURE=1が必要です。

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

機能

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

Claude Code、Cursor、Codex への接続

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

{
  "mcpServers": {
    "timeweb-s3": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TIMEWEB_S3_ACCESS_KEY_ID",
        "-e",
        "TIMEWEB_S3_SECRET_ACCESS_KEY",
        "-e",
        "TIMEWEB_S3_POOL",
        "ghcr.io/stufently/timeweb-s3-mcp-ai-cli:0.1.0"
      ],
      "env": {
        "TIMEWEB_S3_ACCESS_KEY_ID": "${env:TIMEWEB_S3_ACCESS_KEY_ID}",
        "TIMEWEB_S3_SECRET_ACCESS_KEY": "${env:TIMEWEB_S3_SECRET_ACCESS_KEY}",
        "TIMEWEB_S3_POOL": "${env:TIMEWEB_S3_POOL}"
      }
    }
  }
}

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

各レベルは個別に有効化できます：timeweb-s3 mcp --allow-write --allow-delete --allow-admin または TIMEWEB_S3_ALLOW=write,delete,admin。フラグは mcp install でも利用できます。TIMEWEB_S3_FILE_ROOT で 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_delete_bucket

リソース：timeweb-s3://config、timeweb-s3://capabilities、timeweb-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 を使って集計結果のページを返します。これは請求額ではありません。

シナリオ：アーカイブの復元とプレフィックスの使用量の確認

既存のプレフィックスの使用量を見積もり、Timeweb のアーカイブを新しいローカルファイルに復元します。du は確認するオブジェクト数を制限します。partial が付いた結果は、バケット全体の使用量を示すものではありません。トークンを使った続きの取得には、MCP ツール s3_prefix_usage を使用できます。

timeweb-s3 du backups/daily/ --max-scan 10000 --json
timeweb-s3 stat backups/daily/archive.tar
timeweb-s3 cp s3://backups/daily/archive.tar ./restored-timeweb.tar

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

CLI

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

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

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

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

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

デフォルトのインストール先は ~/.claude/skills/timeweb-s3 です。SKILL.md と 6 つの参照ドキュメント（バックアップ／復元、共有、最小権限、コスト管理、移行、インシデント対応）を冪等にインストールします。トリガー：「timeweb s3」、「бакет Timeweb 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 のみを登録します。未対応の機能や不足しているレベルに該当するツールは除外されます。

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

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

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

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

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

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

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

よくある質問

Timeweb S3 を Cursor に接続するには？ timeweb-s3 auth set コマンドでキーを保存し、mcp install --client cursor --dry-run を確認してから、--dry-run を付けずにインストールを実行します。クライアントのファイルに S3 のシークレットは含まれません。

StorageClass で Timeweb のコールド料金プランを選択できますか？ このプロジェクトでは、standard/hot/cold はバケットの料金プラン一覧を表し、X-Amz-Storage-Class ヘッダーの値ではありません。料金プランはパネルから選択してください。詳細はTimeweb の調査結果をご覧ください。

Timeweb で Object Lock を設定するツールがないのはなぜですか？ Object Lock configuration の PUT は、確認が済むまでプロファイルで無効になっています。サービスが備える機能と、プロジェクトに登録されているツールは別のものです。互換性とライブチェックのステータスをご覧ください。

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 と互換性をご覧ください。ツールはプロファイルに基づいて登録されます。このバージョンでは 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、Timeweb Cloud のドキュメントが残ります。