@atengk/mcp-server-s3
基于标准 S3 协议 深度连接与管控兼容对象存储(RustFS、MinIO、AWS S3、阿里云 OSS、Cloudflare R2、腾讯云 COS 等)的生产级 Model Context Protocol (MCP) 服务。为大语言模型(LLM)与 AI 智能体(Claude Desktop、Cursor、Antigravity、Cline、Dify、Coze 等)提供安全、可控、高内聚的对象存储全生命周期管理与数据流动基础设施。
🌟 核心特性 (Features)
- 🌐 多云协议统一驱动:严格基于工业级标准 S3 API 构建,无缝抹平私有化 RustFS、MinIO 与各大公有云差异,支持 Path-style 路径寻址与 Virtual-hosted 虚拟主机寻址自动切换(ADR-0001)。
- ⚡ 双模通信与安全接入:
- 🛡️ 三位一体安全防灾铁律(ADR-0002):
- 前置只读门禁 (
Read-Only Guard):开启MCP_S3_READ_ONLY=true时,在 MCP 握手层物理隐藏所有破坏性写/删类工具; - 工作区沙箱隔离 (
Sandbox Guard):基于MCP_S3_ALLOWED_LOCAL_DIR严格限定本地文件读写边界,彻底阻断路径遍历(../)逃逸与宿主机敏感凭证泄露; - 前缀递归删除三重熔断 (
Prefix Deletion Guard):强制拦截根前缀、强制要求显式布尔确认参数、单批次严格限制 1000 上限,防止误删整个存储桶; - 文本直读智能截断 (
Content Truncator):限制 256KB 文本直读上限,自动截断超量日志并注入警示,彻底杜绝上下文风暴。
- 前置只读门禁 (
- 🚀 大对象分段上传与纯文本深度探测(ADR-0006):
- 自适应 Multipart Upload:大文件(>32MB)自动启用 8MB 分片并发分段上传,彻底突破 5GB 单流上限并增强网络波动抗重试韧性;
- 仿 Git Null Byte 探测:对未显式打标 MIME 的对象检测前 512 字节空字节,宽容放行纯文本与日志,杜绝
application/octet-stream误伤阻断。
- 🛠️ 19 项生产级工具矩阵:覆盖自省探针、存储桶生命周期、虚拟目录树浏览与游标分页、模式搜索、文本与 Range 范围读取、本地磁盘双向流式互传、时效预签名直链、对象原子移动与标签治理。
- 🔍 毫秒级自省探针 (
s3_ping):发送极轻量校验请求,以毫秒级时延返回当前生效 Endpoint、脱敏 AccessKey、Region、网络往返 RTT 及连通状态(ADR-0005)。 - 🐳 生产级轻量容器化:提供 Alpine 多阶段构建
Dockerfile(非 root 用户运行)与开箱即用的docker-compose.yaml(一键拉起 MinIO + S3 MCP 集群)。 - 📦 免安装一键即用:发布至 npm 官方注册表
@atengk/mcp-server-s3,由 GitHub Actions 原生 OIDC 签发不可篡改的 SLSA Provenance 防伪溯源凭证(ADR-0004)。
🚀 快速上手 (Quick Start)
方式一:终端命令行即时启动 (CLI Flags)
@atengk/mcp-server-s3 原生支持双模参数输入体系,命令行参数(CLI Flags)优先级高于环境变量,非常适合临时排障与终端交互:
# 连接自建 RustFS / MinIO (Path-Style 模式)
npx -y @atengk/mcp-server-s3 --endpoint http://s3.example.com:9000 --access-key-id your_access_key --secret-access-key your_secret_key --path-style
# 以安全只读模式启动,限定默认存储桶
npx -y @atengk/mcp-server-s3 --region us-east-1 --bucket prod-public-data --read-only
# 启动 HTTP SSE 远程守护服务(监听 8000 端口,开启密钥鉴权)
npx -y @atengk/mcp-server-s3 --transport sse --port 8000 --api-key secret-token-888
方式二:桌面端 AI 客户端配置 (MCP Client Config)
在您的 MCP 客户端配置文件(如 Claude Desktop 的 claude_desktop_config.json 或 Cursor 的 MCP 设置)中直接声明服务项:
{
"mcpServers": {
"my-s3-storage": {
"command": "npx",
"args": ["-y", "@atengk/mcp-server-s3"],
"env": {
"MCP_S3_ENDPOINT": "http://s3.example.com:9000",
"MCP_S3_REGION": "us-east-1",
"MCP_S3_ACCESS_KEY_ID": "your_access_key",
"MCP_S3_SECRET_ACCESS_KEY": "your_secret_key",
"MCP_S3_FORCE_PATH_STYLE": "true",
"MCP_S3_DEFAULT_BUCKET": "my-bucket"
}
}
}
}
💡 多实例与多云并存体系 (Multi-Instance Configuration)
📌 核心运行机制:环境变量配置如何天然支持多实例?
在 MCP 架构规范中,AI 客户端(Claude Desktop、Cursor 等)为配置列表中的每一个服务项启动一个独立的操作系统子进程 (Child Process)。 每个服务进程各自持有完全隔离的
env环境变量字典,进程间完全物理隔离,绝不会产生交叉污染或覆盖。 因此,您可以在同一个 AI 客户端中同时接入多个不同云服务商、不同权限环境的对象存储服务!
完整多实例并存配置范例
在同一个客户端配置文件中,同时接入 RustFS (私有云)、MinIO (本地开发) 以及 AWS S3 (生产只读):
{
"mcpServers": {
"s3-rustfs": {
"command": "npx",
"args": ["-y", "@atengk/mcp-server-s3"],
"env": {
"MCP_S3_ENDPOINT": "http://rustfs.example.com:9000",
"MCP_S3_REGION": "us-east-1",
"MCP_S3_ACCESS_KEY_ID": "rustfsadmin",
"MCP_S3_SECRET_ACCESS_KEY": "your_secret_key",
"MCP_S3_FORCE_PATH_STYLE": "true"
}
},
"s3-local-minio": {
"command": "npx",
"args": ["-y", "@atengk/mcp-server-s3"],
"env": {
"MCP_S3_ENDPOINT": "http://127.0.0.1:9000",
"MCP_S3_REGION": "us-east-1",
"MCP_S3_ACCESS_KEY_ID": "minioadmin",
"MCP_S3_SECRET_ACCESS_KEY": "minioadmin",
"MCP_S3_FORCE_PATH_STYLE": "true",
"MCP_S3_DEFAULT_BUCKET": "dev-bucket"
}
},
"s3-prod-aws": {
"command": "npx",
"args": ["-y", "@atengk/mcp-server-s3"],
"env": {
"MCP_S3_REGION": "us-west-2",
"MCP_S3_ACCESS_KEY_ID": "AKIAIOSFODNN7EXAMPLE",
"MCP_S3_SECRET_ACCESS_KEY": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
"MCP_S3_READ_ONLY": "true",
"MCP_S3_DEFAULT_BUCKET": "company-prod-data"
}
}
}
}
- 调度体验:在对话中,AI 能够跨实例自如调度:
- 调用
s3-rustfs:s3_ping检视 RustFS 节点时延与状态; - 调用
s3-local-minio:upload_file将本地构建产物传输至开发桶; - 调用
s3-prod-aws:read_object_text检索生产线上日志(写与删操作被物理门禁彻底阻断,保障数据安全)。
- 调用
⚙️ 主流对象存储场景配置参考 (Scenarios)
{
"mcpServers": {
"rustfs": {
"command": "npx",
"args": ["-y", "@atengk/mcp-server-s3"],
"env": {
"MCP_S3_ENDPOINT": "http://rustfs.example.com:9000",
"MCP_S3_REGION": "us-east-1",
"MCP_S3_ACCESS_KEY_ID": "rustfsadmin",
"MCP_S3_SECRET_ACCESS_KEY": "your_secret_key",
"MCP_S3_FORCE_PATH_STYLE": "true"
}
}
}
}
{
"mcpServers": {
"minio": {
"command": "npx",
"args": ["-y", "@atengk/mcp-server-s3"],
"env": {
"MCP_S3_ENDPOINT": "http://127.0.0.1:9000",
"MCP_S3_REGION": "us-east-1",
"MCP_S3_ACCESS_KEY_ID": "minioadmin",
"MCP_S3_SECRET_ACCESS_KEY": "minioadmin",
"MCP_S3_FORCE_PATH_STYLE": "true"
}
}
}
}
{
"mcpServers": {
"aws-s3": {
"command": "npx",
"args": ["-y", "@atengk/mcp-server-s3"],
"env": {
"MCP_S3_REGION": "us-west-2",
"MCP_S3_ACCESS_KEY_ID": "AKIAIOSFODNN7EXAMPLE",
"MCP_S3_SECRET_ACCESS_KEY": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
}
}
}
}
{
"mcpServers": {
"aliyun-oss": {
"command": "npx",
"args": ["-y", "@atengk/mcp-server-s3"],
"env": {
"MCP_S3_ENDPOINT": "https://oss-cn-hangzhou.aliyuncs.com",
"MCP_S3_REGION": "oss-cn-hangzhou",
"MCP_S3_ACCESS_KEY_ID": "LTAI5txxxxxxxxxxxx",
"MCP_S3_SECRET_ACCESS_KEY": "your_aliyun_secret",
"MCP_S3_FORCE_PATH_STYLE": "false"
}
}
}
}
{
"mcpServers": {
"cloudflare-r2": {
"command": "npx",
"args": ["-y", "@atengk/mcp-server-s3"],
"env": {
"MCP_S3_ENDPOINT": "https://<account_id>.r2.cloudflarestorage.com",
"MCP_S3_REGION": "auto",
"MCP_S3_ACCESS_KEY_ID": "your_r2_access_key_id",
"MCP_S3_SECRET_ACCESS_KEY": "your_r2_secret_access_key"
}
}
}
}
{
"mcpServers": {
"tencent-cos": {
"command": "npx",
"args": ["-y", "@atengk/mcp-server-s3"],
"env": {
"MCP_S3_ENDPOINT": "https://cos.ap-guangzhou.myqcloud.com",
"MCP_S3_REGION": "ap-guangzhou",
"MCP_S3_ACCESS_KEY_ID": "AKIDxxxxxxxxxxxxxxxx",
"MCP_S3_SECRET_ACCESS_KEY": "your_cos_secret_key",
"MCP_S3_FORCE_PATH_STYLE": "false"
}
}
}
}
🤖 典型 AI 智能体对话调度场景 (Prompt Showcase)
接入 @atengk/mcp-server-s3 后,您可以直接使用自然语言驱动 AI 智能体完成高阶存储运维工作:
# 场景 1:连通性诊断与节点状态检视
> "帮我测试一下对象存储的连通性,看看当前的延迟、生效地域和绑定的默认存储桶。"
→ AI 自动触发: s3_ping
# 场景 2:虚拟目录树分层探索与检索
> "列出 backup 桶下 logs/2026/03/ 目录里的所有文件,找出大小超过 10MB 的前 5 个对象。"
→ AI 自动触发: list_objects(prefix="logs/2026/03/", delimiter="/")
# 场景 3:线上大日志精准定位排障
> "app.log 文件有 500MB,帮我直接读取最后 4KB 的内容分析报错原因,不要下载整个文件。"
→ AI 自动触发: stat_object(key="app.log") 获取总大小,随后调用 read_object_range 提取末尾字节
# 场景 4:双向安全文件互传与时效分享
> "将本地 ./dist/report.pdf 上传到 public 桶,并生成一个 2 小时有效期的下载直链发给我。"
→ AI 自动触发: upload_file(local_path="./dist/report.pdf") 紧接着 get_presigned_url(expires_in=7200)
# 场景 5:归档迁移与标签治理
> "把 temp 桶中 2025 年以前的所有对象归档,打上 retention=archive 标签并移动到 archive/ 目录下。"
→ AI 自动调度: list_objects + set_object_tags + move_object
🛠️ 19 项核心工具矩阵清单 (Tools Matrix)
服务向 AI 暴露了严格遵循最小权限与防御性架构的 19 项原子工具:
1. 探针自省与桶生命周期管理
2. 对象检索与内容分块直读
3. 本地磁盘双向流式互传与时效直链
4. 批处理治理与标签管控
📋 12-Factor 规范环境变量矩阵 (Configuration)
配置优先级:命令行参数 (CLI Flags) > 规范主环境变量 (MCP_S3_*) > AWS 兼容环境变量 (AWS_*) > 内部默认值。
⚡ 命令行参数完整速查表 (CLI Flags)
🐳 云原生容器化部署与 HTTP SSE 鉴权 (Docker & SSE)
对于希望在私有网络或云上集中托管 S3 MCP 服务的场景,可直接使用容器化方案常驻运行:
1. 使用 Docker Compose 一键启动微服务集群
docker-compose.yaml 默认直接拉取 GitHub Packages (GHCR) 发布的预编译多架构镜像(ghcr.io/atengk/mcp-server-s3:latest),无需本地安装 Node/pnpm 或进行耗时编译,甚至仅需单独下载单份 docker-compose.yaml 即可秒级拉起完整的 MinIO + S3 MCP 集群:
# 后台拉起微服务集群 (MinIO + 预编译 S3 MCP)
docker compose up -d
# 检查服务就绪探针 (健康检查公开免鉴权)
curl http://localhost:8000/health
💡 进阶提示:如需锁定特定版本,可运行
MCP_S3_IMAGE_TAG=v1.0.1 docker compose up -d;如需基于本地源码二次开发,仅需按docker-compose.yaml中提示解除build注释即可。
2. 远程 HTTP SSE 鉴权接入规范
当设置了 MCP_S3_API_KEY=your-secret-token 时,服务将自动启用 CORS 与双栈校验机制:
# 方式 1: 通过标准 Authorization Bearer 请求头连接 SSE (推荐桌面/网关客户端)
curl -N -H "Authorization: Bearer your-secret-token" http://localhost:8000/sse
# 方式 2: 通过 URL 查询参数连接 SSE (适配原生浏览器 EventSource API)
curl -N "http://localhost:8000/sse?token=your-secret-token"
# 发送 JSON-RPC 消息 (带 Bearer Token)
curl -X POST -H "Authorization: Bearer your-secret-token" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"ping","id":1}' \
"http://localhost:8000/message?sessionId=<SESSION_ID>"
🛡️ 三位一体安全防灾体系 (Security Guardrails)
AI Agent 发起请求
│
┌─────────────────┴─────────────────┐
│ │
[写/删高危操作] [文件读写操作]
│ │
▼ ▼
【Read-Only Guard 检查】 【Sandbox Guard 校验】
(若开启只读则协议层隐藏/阻断) (判断是否处于受管本地工作区内)
│ │
▼ ▼
【Prefix Deletion Guard 检查】 【Content Truncator 过滤】
• 严禁根前缀 ("" 或 "/") • 限制最大单次读取 256KB
• 强制显式 confirm 参数 • 超出部分截断并注入警示
• 单批次强制截断上限 1000 • 二进制 Null Byte 智能拦截
❓ 常见问题排查 (FAQ)
Q1: 连接 MinIO 或 RustFS 时报 PermanentRedirect 或 BucketRegionError?
解答:私有化对象存储(MinIO、RustFS)默认采用 Path-Style 路径寻址(格式如 http://endpoint/bucket/key)。若未显式启用,SDK 将尝试向虚拟主机域名 http://bucket.endpoint/ 发起 DNS 解析并导致失败。请确保设置:
- 环境变量:
MCP_S3_FORCE_PATH_STYLE=true - 或命令行选项:
--path-style
Q2: 提示 Forbidden: Path traversal or access outside sandbox is prohibited?
解答:服务内置严格的工作区沙箱保护(ADR-0002),禁止访问 MCP_S3_ALLOWED_LOCAL_DIR 范围之外的绝对路径或带有 ../ 的路径。请将文件操作限制在沙箱基准目录内,或通过修改 --allowed-local-dir /path/to/workdir 扩大授权范围。
Q3: 为什么开启 MCP_S3_READ_ONLY=true 后 AI 看不到上传或删除工具?
解答:这是我们深思熟虑的安全设计。只读门禁不是在运行时抛出拒绝异常,而是在 MCP 握手初期的 tools/list 协议层物理移除了所有破坏性写/删类工具定义。这样既能 100% 杜绝 AI 误执行写删行为,又能有效缩减提示词体积,防止上下文污染。
📊 架构设计与工程分层 (Architecture)
src/
├── config/ # 12-Factor App 强类型环境配置与 CLI 命令行解析 (env.ts, cli.ts)
├── connection/ # S3Client 连接单例工厂与凭据链管理 (s3-client-factory.ts)
├── security/ # 只读门禁、沙箱验证、递归删除三重防御、文本截断器 (readonly-guard.ts, sandbox-guard.ts, prefix-guard.ts, content-truncator.ts)
├── services/ # 领域服务分治(Bucket、Object、Transfer、Presign、Tagging、Probe 逻辑)
├── server/ # Stdio 与 HTTP SSE 双模服务实现与安全门禁 (sse-server.ts)
├── types/ # 领域接口契约与 Zod 运行时校验 Schema
└── index.ts # 装配入口、CLI 调度与进程信号优雅退出管理
📝 统一领域模型与架构决策 (Domain Model & ADRs)
- 统一领域语言与术语表:详见 CONTEXT.md
- 核心架构决策记录 (ADRs):
🤝 贡献与开源许可 (License)
本项目采用 MIT License 开源协议。
Copyright (c) 2026 Ateng.