s3

S3 MCP 服务

用于执行 AWS S3 操作的 MCP 服务，具备精细的工具访问控制。支持对 S3 存储桶和对象进行读写操作，并可配置工具组以管理安全性和权限。

亮点

• 全面的 S3 存储桶和对象管理（列出、获取、上传、复制、删除）
• 通过工具组进行精细的访问控制（只读、读写）
• 通过环境变量单独启用或禁用工具
• 通过运行状况检查验证 AWS 凭证
• 支持兼容 S3 的端点（MinIO、LocalStack 等）
• 使用 TypeScript，并启用严格类型检查
• 全面的测试（功能、集成、手动）

功能

工具

工具	组	描述
list_buckets	readonly	列出 AWS 账户中的所有 S3 存储桶
list_objects	readonly	列出存储桶中的对象，支持前缀和分页
get_object	readonly	以文本形式获取对象内容
head_bucket	readonly	检查存储桶是否存在且可访问
put_object	readwrite	上传或更新对象
delete_object	readwrite	删除存储桶中的对象
copy_object	readwrite	在同一存储桶内或不同存储桶之间复制对象
create_bucket	readwrite	创建新的 S3 存储桶
delete_bucket	readwrite	删除空的 S3 存储桶

资源

资源	描述
s3://config	服务配置和状态（用于调试）

工具组

通过 S3_ENABLED_TOOLGROUPS 环境变量控制可用工具：

组	描述
readonly	只读操作（列出、获取、检查）
readwrite	写入操作（上传、删除、复制、创建）

示例：

• S3_ENABLED_TOOLGROUPS="readonly" - 仅启用读操作
• S3_ENABLED_TOOLGROUPS="readonly,readwrite" - 启用所有操作
• 未设置 - 启用所有工具（默认）

单独控制工具

对特定工具进行精细控制：

• S3_ENABLED_TOOLS="list_buckets,get_object" - 仅启用这些工具
• S3_DISABLED_TOOLS="delete_bucket,delete_object" - 禁用这些工具

单存储桶模式

使用 S3_BUCKET 将所有操作限制在特定存储桶中：

S3_BUCKET="my-bucket"

设置后：

• 所有对象操作都会自动限定在此存储桶中
• 存储桶级工具（list_buckets、create_bucket、delete_bucket、head_bucket）将被隐藏
• bucket 参数会自动注入，并从工具输入中隐藏
• 对于 copy_object，源和目标都会被限制在指定的存储桶中

此模式适用于将访问限制在单个存储桶内，同时避免授予更广泛的 S3 权限。

快速开始

配置

环境变量

变量	必填	说明	默认值
AWS_ACCESS_KEY_ID	是	AWS 访问密钥 ID	-
AWS_SECRET_ACCESS_KEY	是	AWS 访问密钥	-
AWS_REGION	否	S3 操作所用的 AWS 区域	us-east-1
AWS_ENDPOINT_URL	否	自定义 S3 端点（用于 MinIO 等）	-
S3_FORCE_PATH_STYLE	否	使用路径样式寻址（用于 MinIO）	false
S3_BUCKET	否	将操作限制在单个存储桶内	-
S3_ENABLED_TOOLGROUPS	否	以逗号分隔的工具组	全部启用
S3_ENABLED_TOOLS	否	要启用的特定工具	-
S3_DISABLED_TOOLS	否	要禁用的特定工具	-
SKIP_HEALTH_CHECKS	否	跳过凭据验证	false

Claude Desktop 配置

如果你是首次使用 MCP 服务，请确保已安装 Claude Desktop 应用程序，并按照 官方 MCP 设置说明进行操作。

macOS：~/Library/Application Support/Claude/claude_desktop_config.json

Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "s3": {
      "command": "npx",
      "args": ["-y", "s3-aws-mcp-server"],
      "env": {
        "AWS_ACCESS_KEY_ID": "your-access-key-id",
        "AWS_SECRET_ACCESS_KEY": "your-secret-access-key",
        "AWS_REGION": "us-east-1",
        "S3_ENABLED_TOOLGROUPS": "readonly"
      }
    }
  }
}

重启 Claude Desktop 后即可开始使用！

只读模式

为更安全地探索，请仅启用读取操作：

{
  "env": {
    "S3_ENABLED_TOOLGROUPS": "readonly"
  }
}

与兼容 S3 的服务搭配使用

对于 MinIO、LocalStack 或其他兼容 S3 的服务：

{
  "env": {
    "AWS_ACCESS_KEY_ID": "minioadmin",
    "AWS_SECRET_ACCESS_KEY": "minioadmin",
    "AWS_REGION": "us-east-1",
    "AWS_ENDPOINT_URL": "http://localhost:9000",
    "S3_FORCE_PATH_STYLE": "true"
  }
}

注意： 对于 MinIO 以及某些使用路径样式寻址（localhost:9000/bucket-name）而非虚拟主机样式（bucket-name.localhost:9000）的兼容 S3 服务，必须设置 S3_FORCE_PATH_STYLE。

开发

安装依赖项

npm run install-all

构建

npm run build

在开发模式下运行

npm run dev

测试

# Run functional tests
npm run test:run

# Run integration tests (full MCP protocol)
npm run test:integration

# Run manual tests (real AWS - requires .env)
npm run test:manual:setup  # First time only
npm run test:manual

# Run all automated tests
npm run test:all

手动测试设置

在 s3 目录中创建 .env 文件：

AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
AWS_REGION=us-east-1

然后运行：

npm run test:manual

项目结构

s3/
├── local/                 # Local server implementation
│   ├── src/
│   │   ├── index.ts      # Main entry point with env validation
│   │   └── index.integration-with-mock.ts
│   └── package.json
├── shared/               # Shared business logic
│   ├── src/
│   │   ├── server.ts     # Server factory with DI
│   │   ├── tools.ts      # Tool registration with grouping
│   │   ├── tools/        # Individual tool implementations
│   │   ├── resources.ts  # Resource implementations
│   │   ├── s3-client/    # AWS S3 client wrapper
│   │   └── logging.ts
│   └── package.json
├── tests/                # Test suite
│   ├── functional/       # Unit tests with mocks
│   ├── integration/      # MCP protocol tests
│   ├── manual/          # Real API tests
│   └── mocks/           # Mock implementations
└── package.json         # Root workspace config

许可证

MIT