selectel-s3-mcp-ai-cli

Selectel S3 MCP Server & AI CLI

用于 Selectel S3（Selectel Object Storage）的 MCP 服务和 CLI，可连接 Claude Code、Cursor 和 Codex，浏览存储桶、恢复备份，并通过 Go 二进制文件 selectel-s3 操作文件。

English guide · S3 MCP 服务目录

English

A Go MCP server, CLI and agent skill for Selectel S3 Object Storage. Connect Claude Code, Cursor and Codex to scoped object storage for inspection and backup recovery. Six profile pools; tagging and lifecycle tools are disabled. See the full English guide.

功能

• 对象 CRUD、服务端复制/移动、版本、多段上传、预签名 GET/PUT。
• CORS、存储桶策略和 Object Lock 配置；根据配置文件的能力注册。
• 有限扫描：大型对象、前缀使用情况、未完成的上传。
• 流式 CLI、JSON、诊断、MCP 配置和内置 skill 安装。

快速开始

从 Releases 下载适用于你平台的二进制文件（已发布 v0.1.0；已收录于 MCP Registry 和 Smithery），或使用 Go 1.27.2 构建：

go build -o selectel-s3 ./cmd/selectel-s3
./selectel-s3 version
./selectel-s3 auth set
./selectel-s3 auth status
./selectel-s3 ls --json

auth set 会在不回显的情况下询问 key ID 和 secret；没有 TTY 时则从 stdin 读取两行。不要通过 argv 传递 secret。文件 ~/.config/selectel-s3/credentials 会以原子方式创建，权限为 0600；权限更宽松的文件会被拒绝。

优先级：标志 > env > 文件。变量：SELECTEL_S3_ACCESS_KEY_ID、SELECTEL_S3_SECRET_ACCESS_KEY、SELECTEL_S3_POOL（ru-1）、SELECTEL_S3_ENDPOINT。使用 HTTP 时需要设置 SELECTEL_S3_ALLOW_INSECURE=1。

镜像：ghcr.io/stufently/selectel-s3-mcp-ai-cli:0.1.0；本地构建：docker build -t selectel-s3 . 镜像以 uid 65532 运行 MCP，并包含 CA 证书。通过私有环境或文件传递凭据。

连接到 Claude Code、Cursor、Codex

此按钮会从 Docker 镜像 ghcr.io/stufently/selectel-s3-mcp-ai-cli:0.1.0 安装仅限读取模式的 MCP。密钥不会写入配置：Cursor 会从环境中替换 ${env:…}，因此请在启动 Cursor 的环境中设置 SELECTEL_S3_ACCESS_KEY_ID 和 SELECTEL_S3_SECRET_ACCESS_KEY；如果存储桶不在默认池中，还需设置 SELECTEL_S3_POOL（空值 = 默认池）。同一配置块也适用于 Windsurf（mcp_config.json），或可手动写入 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "selectel-s3": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "SELECTEL_S3_ACCESS_KEY_ID",
        "-e",
        "SELECTEL_S3_SECRET_ACCESS_KEY",
        "-e",
        "SELECTEL_S3_POOL",
        "ghcr.io/stufently/selectel-s3-mcp-ai-cli:0.1.0"
      ],
      "env": {
        "SELECTEL_S3_ACCESS_KEY_ID": "${env:SELECTEL_S3_ACCESS_KEY_ID}",
        "SELECTEL_S3_SECRET_ACCESS_KEY": "${env:SELECTEL_S3_SECRET_ACCESS_KEY}",
        "SELECTEL_S3_POOL": "${env:SELECTEL_S3_POOL}"
      }
    }
  }
}

selectel-s3 mcp install --client cursor --dry-run
selectel-s3 mcp install --client cursor
selectel-s3 mcp install --client claude-desktop
selectel-s3 mcp install --client codex
selectel-s3 mcp install --client claude-code --scope project
selectel-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；只有 # >>> selectel-s3 (managed) / # <<< selectel-s3 (managed) 之间的区块会被替换。没有标记的表格即使使用 --force 也不会替换；TOML 的其他字节保持不变。

各级权限可独立启用：selectel-s3 mcp --allow-write --allow-delete --allow-admin 或 SELECTEL_S3_ALLOW=write,delete,admin。mcp install 也支持这些标志。通过 SELECTEL_S3_FILE_ROOT 启用 FILE_ROOT。

MCP 工具

级别	工具
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
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
write + FILE_ROOT	s3_upload_file
delete	s3_delete_object, s3_delete_objects, s3_multipart_abort
write + delete	s3_move_object
admin	s3_create_bucket, s3_put_bucket_versioning, s3_put_bucket_cors, s3_put_bucket_policy, s3_delete_bucket_policy, s3_put_object_lock_configuration
admin + delete	s3_delete_bucket

Selectel 不会注册标签。资源：selectel-s3://config、selectel-s3://capabilities、selectel-s3://pools。

列表最多包含 1000 个项目，并使用 continuation_token；版本和 multipart 操作还有第二个标记。Inline get/put 限制为 262144 字节，preview 限制为 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 返回聚合数据分页。这不是计费数据。

场景：选择存储池并恢复备份

选择现有存储桶的存储池，并在恢复前检查存档。--pool 会同时更改 endpoint 和签名区域；对于莫斯科存储池 ru-6，示例如下：

selectel-s3 --pool ru-6 ls backups/daily/ --json
selectel-s3 --pool ru-6 stat backups/daily/archive.tar
selectel-s3 --pool ru-6 cp s3://backups/daily/archive.tar ./restored-selectel.tar

示例使用现有存储桶 backups 和对象 daily/archive.tar；请替换为自己的值。配置文件和云 API 仍需实际验证。

CLI

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

cp 接受常规本地路径和 S3 URI s3://bucket/key 或 selectel-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 技能

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

默认路径为 ~/.claude/skills/selectel-s3。以幂等方式安装 SKILL.md 和六个 references：backup/restore、share、least privilege、cost hygiene、migration、incident response。触发词：「selectel s3」「бакет селектел」「загрузи в s3」「presigned」「бэкап в s3」。

安全

MCP 默认仅注册 read；不支持的能力和缺失的权限级别会导致工具不注册。

SELECTEL_S3_DESTRUCTIVE_POLICY：confirm 在客户端支持时使用 elicitation，否则需要在人类同意后设置 confirm:true；elicit 要求支持 elicitation，且不能通过 confirm:true 绕过；block 始终禁止操作，allow 则不经门控直接执行。拒绝操作优先于任何 S3 请求。门控涵盖删除、move、presigned PUT、策略/Object Lock、暂停 versioning 和覆盖。

put/copy/move/multipart complete/upload file 默认设置 overwrite:false：对目标执行 HEAD，并使用 If-None-Match: *。overwrite:true 需要通过同一门控。

范围：SELECTEL_S3_ALLOWED_BUCKETS=backups 和 SELECTEL_S3_ALLOWED_PREFIXES=backups/daily/。前缀按路径段边界匹配；daily-evil 不匹配。拒绝 '..' 路径段。范围不完整时，即使某个桶在 ALLOWED_BUCKETS 中，也会禁止对整个桶的操作和宽泛列表查询。Copy/move 会检查源和目标。

文件 MCP 工具使用 os.Root：仅允许 FILE_ROOT 内的相对路径；拒绝 '..'、绝对路径和指向外部的符号链接。每次调用都会向 stderr 写入一行 JSON；SELECTEL_S3_AUDIT_FILE 还会以 0600 权限写入日志。日志/错误会对密钥和 X-Amz-Signature/Credential/Security-Token 进行脱敏。完整的签名链接仅作为操作结果返回。还应限制 S3 密钥本身的权限。

s3_download_file 默认会发布下载的文件，但不会替换已有文件，包括下载期间创建的文件。若要替换，请传入 overwrite:true：这会应用破坏性策略，并通过表单确认，或在人类同意后设置 confirm:true。

Selectel 存储池和存储类别

ru-1 和 ru-3 位于圣彼得堡；ru-6 (Multi-AZ)、ru-7、gis-1（隔离的 GIS）位于莫斯科；uz-2 位于乌兹别克斯坦。SigV4 区域与存储池相同；默认使用 path-style。端点和兼容性。

标准、冷存储、冰存储；冰存储仅适用于 ru-3。存储类别在创建时于控制面板中选择，之后无法更改；create_bucket 不接受存储类别。价格为 2.56 / 1.25 / 0.89 ₽/GB·月——这是所有者提供的未经核实的 2026-10 汇总数据。presigned 的最长 604800 秒也未经确认；文档称请求签名有效期为 15 分钟。

对象最大 50 TB，单次 PUT 最大 5 GB，multipart 最多 10000 个分片。每个桶的请求速率限制：总计 2000 次/秒，GET+HEAD 为 1000 次/秒，POST 为 200 次/秒，PUT 和 DELETE 各为 300 次/秒；超出限制会返回 429。TTL 在控制面板中设置，并应用于新对象。

FAQ

如何为 MCP 选择 Selectel S3 区域？ 设置 SELECTEL_S3_POOL，或使用 --pool 标志指定兼容性表中的标识符。存储池必须与存储桶的存储池一致；默认值为 ru-1。

可以通过此 MCP 服务配置 Selectel 的生命周期和标签吗？ 项目配置文件中已关闭这些功能，因此不会注册相应工具。通过控制面板设置 TTL 的说明见 Selectel 研究。

如何从 Selectel S3 恢复备份？ 使用 stat，然后执行 cp s3://bucket/key ./new-file。CLI 会以流式方式下载，并原子化发布本地文件；使用新路径可以避免替换现有存档。

什么是 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 仍是独立的传输/自动化工具。

为什么没有生命周期和标签？ Selectel S3 API 不支持这些功能。新对象的 TTL 在控制面板中设置；标签已从配置文件中排除。

Другие провайдеры

Общий каталог: MCP-серверы и CLI для российских S3.

Провайдер	Репозиторий	Сценарий
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 и документы Selectel.