timeweb-s3-mcp-ai-cli

Timeweb Cloud S3 MCP 服务与 AI CLI

用于 Timeweb Cloud（Таймвеб）S3 的 MCP 服务和 CLI，可通过 Claude Code、Cursor 和 Codex 浏览对象、检查备份大小并下载存档。二进制文件 timeweb-s3 会单独连接到 S3 API，不受控制台中所选存储桶套餐的影响。

English guide · S3 MCP 服务目录

English

用于 Timeweb Cloud S3 Object Storage 的 Go MCP 服务、CLI 和 Agent 技能。将 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 会提示输入 key ID 和 secret，输入时不回显；没有 TTY 时会从 stdin 读取两行。不要将 secret 传入 argv。文件 ~/.config/timeweb-s3/credentials 会以 0600 权限原子创建；权限更宽时会被拒绝。

优先级：标志 > 环境变量 > 文件。环境变量：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 证书。请通过私有环境或文件传递凭据。

功能

• 在配置文件限定范围内执行流式 object CRUD、copy、multipart 和 presigned URL 操作。
• 在支持的情况下，注册版本、标签、CORS、策略和 Object Lock configuration。
• 提供受限扫描、诊断、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 — 使用对应操作系统的配置目录。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 工具

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
admin + delete	s3_delete_bucket

资源：timeweb-s3://config、timeweb-s3://capabilities、timeweb-s3://pools。不支持的功能不会提供相应工具。

列表最多包含 1000 个条目，并带有 continuation_token；版本和 multipart 列表还会提供第二个标记。Inline get/put 限制为 262144 字节，preview 限制为 65536 字节；较大的文件通过 presigned URL 或 FILE_ROOT 处理。响应包含 structuredContent 和 JSON 文本；超过 256 KiB 的文本会被简短摘要替代。错误包含 code/message/retryable；SDK 会对 429/503 错误进行自适应重试。

分析最多扫描 max_scan 个对象（默认 10000）；partial/token 表示结果不完整。Prefix usage 会通过 next_result_offset 提供聚合结果分页。这不是计费数据。

场景：恢复归档并统计前缀容量

评估现有前缀的容量，并将 Таймweb 归档恢复到新的本地文件。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 并确认；下载是原子操作。在非 TTY 环境中，rm/rb/mv 不带 --yes 时返回代码 2；在 TTY 环境中会询问。--json 为通用选项；错误输出到 stderr，并返回非零代码。

doctor 会检查来源/凭据权限、DNS/TLS、通过 Date 检查时钟，并调用 ListBuckets：偏差超过 5 分钟时发出警告，超过 15 分钟时报告错误。

面向 AI Agent 的 Skill

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

默认安装在 ~/.claude/skills/timeweb-s3。以幂等方式安装 SKILL.md 和六个参考文件：备份/恢复、共享、最小权限、成本管理、迁移、事件响应。触发词：「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 默认只注册读取工具；不支持的功能和缺失的层级会导致相应工具被排除。

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 输出一行 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 兼容性。

常见问题

如何将 S3 Timeweb 连接到 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 的工具？ 在确认之前，配置文件中会禁用 PUT Object Lock configuration。服务支持某项功能与项目中注册了对应工具是两回事；请参阅 兼容性 和实时检查状态。

什么是 MCP 服务？ 程序通过 Model Context Protocol 向 Agent 提供工具和资源；此处使用 stdio。

如何将 MCP 服务连接到 Claude Code？ 保存密钥并运行 auth set，然后使用 project install，或者使用打印出的 user 命令。

允许 Agent 访问 S3 是否安全？ 请限制密钥、作用域和权限级别；保留 confirm/block，并审慎批准破坏性操作。

这与 aws-cli 和 rclone 有何不同？ 该二进制文件集成了 MCP、网关、审计、分析、skill 和 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 文档。