AI导哈

S3 MCP服务器

一个通过安全接口暴露AWS S3操作的模型上下文协议(MCP)服务器，提供桶/对象列表和预签名URL生成功能，适用于集成Claude Desktop等MCP客户端。

  • by khuynh22
  • JavaScript
  • 本地部署
  • 4 星标
  • 更新于
在 GitHub 查看 khuynh22/aws-s3-mcp-server

使用说明

AWS S3 MCP服务器

模型上下文协议（MCP）服务器，通过安全、定义良好的接口公开AWS S3操作。此服务器提供用于列出存储桶和对象以及生成预签名URL以实现安全数据访问的工具。

非常适合将S3与Claude Desktop和其他MCP客户端集成！

特性

  • 列出Buckets：枚举AWS帐户中的所有S3存储桶
  • 列出对象：使用可选前缀过滤浏览bucket中的对象
  • 预先签名的GET URL：为下载对象生成安全的临时URL
  • 预设的PUT URL：为上传对象生成安全的临时URL（可选，需要ALLOW_WRITE标志）
  • 输入验证：所有输入都使用Zod模式进行验证
  • 日志记录：使用Pino进行结构化日志记录
  • 默认安全：除非明确启用，否则写入操作将被禁用
  • 交叉平台的：适用于Windows、Mac和Linux

🚀 快速开始

最快的设置

# 1. Install and build
npm install
npm run build

# 2. Configure AWS credentials
cp .env.example .env
# Edit .env with your AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION

# 3. Test connection
node examples/quick-test.js

4.添加到您的MCP客户端

适用于克劳德桌面 -编辑 claude_desktop_config.json:

{
  "mcpServers": {
    "aws-s3": {
      "command": "node",
      "args": ["/absolute/path/to/aws-s3-mcp-server/dist/index.js"]
    }
  }
}

VS代码 -编辑 ~/.vscode/mcp.json:

{
  "servers": {
    "aws-s3": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/aws-s3-mcp-server/dist/index.js"]
    }
  }
}

将路径替换为实际安装目录。

5.测试它

  • 克劳德桌面： 重启→ 询问“列出我的S3存储桶”
  • VS代码： 重新加载窗口→ @aws-s3 list my buckets

📖 完整指南： QUICKSTART.md

文档

安装

npm install
npm run build

配置

创建一个 .env 根目录中的文件（请参见 .env.example):

# Required
AWS_ACCESS_KEY_ID=your_access_key_here
AWS_SECRET_ACCESS_KEY=your_secret_key_here
AWS_REGION=us-east-1

# Optional: Enable write operations (presign_put)
ALLOW_WRITE=false

# Optional: Set log level (default: info)
LOG_LEVEL=info

📖 有关详细的设置说明，请参阅 SETUP_GUIDE.md

用法

服务器使用stdio传输并通过标准输入/输出进行通信，使其适合与Claude Desktop等MCP客户端集成。

独立运行

npm start

常见操作

列出所有桶：

"Show me all my S3 buckets"

列出bucket中的对象：

"List all files in my-data-bucket"

获取下载链接：

"Give me a download link for report.pdf in my-docs-bucket"

获取上传链接（如果ALLOW_WRITE=true）：

"Generate an upload URL for new-file.json in my-bucket"

📖 有关完整的使用示例，请参阅 用法_ GIDE.md

可用工具

1. s3_list_buckets

列出AWS帐户中的所有S3存储桶。

输入：无

示例响应:

[
  {
    "name": "my-bucket",
    "creationDate": "2024-01-01T00:00:00.000Z"
  }
]

2. s3_list_objects

列出S3存储桶中的对象，并可选择过滤。

输入:

  • bucket （必填）：S3存储桶的名称
  • prefix （可选）：按前缀过滤对象
  • maxKeys （可选）：要返回的最大对象数（1-1000）

示例响应:

{
  "objects": [
    {
      "key": "path/to/file.txt",
      "size": 1024,
      "lastModified": "2024-01-01T00:00:00.000Z",
      "etag": "\"abc123\""
    }
  ],
  "isTruncated": false,
  "keyCount": 1
}

3. s3_presign_get

生成用于下载对象的预签名URL。

输入:

  • bucket （必填）：S3存储桶的名称
  • key （必填）：对象键
  • expiresIn （可选）：URL过期时间（秒）（默认值：3600，最大值：604800）

示例响应:

{
  "url": "https://bucket.s3.amazonaws.com/key?X-Amz-Algorithm=...",
  "expiresIn": 3600,
  "bucket": "my-bucket",
  "key": "path/to/file.txt"
}

4. s3_presign_put

生成用于上传对象的预签名URL（需要 ALLOW_WRITE=true).

输入:

  • bucket （必填）：S3存储桶的名称
  • key （必填）：对象键
  • expiresIn （可选）：URL过期时间（秒）（默认值：3600，最大值：604800）
  • contentType （可选）：对象的内容类型

示例响应:

{
  "url": "https://bucket.s3.amazonaws.com/key?X-Amz-Algorithm=...",
  "expiresIn": 3600,
  "bucket": "my-bucket",
  "key": "path/to/file.txt",
  "contentType": "application/json"
}

发展

构建

npm run build

观看模式

npm run dev

运行测试

npm test

棉绒

npm run lint

快速连接测试

node examples/quick-test.js

故障排除

服务器在Claude中没有响应

  1. 检查克劳德桌面日志：帮助→ 显示日志
  2. 验证配置中的服务器路径是否正确（使用绝对路径）
  3. 手动测试： node dist/index.js
  4. 重新启动克劳德桌面

AWS连接问题

错误：缺少凭据

  • 验证 .env 文件存在于项目根目录中
  • 检查环境变量中没有多余的空格
  • 确保文件命名准确 .env （不是 .env.txt)

错误：拒绝访问

  • 验证IAM用户是否具有S3权限
  • 检查指定区域是否存在铲斗
  • 测试证书： node examples/quick-test.js

错误：访问密钥无效

  • 验证AWS_ACCESS_KEY_ID是否正确
  • 检查AWS_SECRET_ACCESS_KEY匹配项
  • 确保凭据未被轮换/删除

写入操作不起作用

  • 集 ALLOW_WRITE=true 在 .env 文件
  • 重新启动MCP服务器
  • 验证IAM用户是否具有PutObject权限

性能问题

对于包含数百万个对象的桶：

  • 使用前缀过滤： "List files in my-bucket with prefix 'logs/2024/'"
  • 限制结果： "Show first 100 files in my-bucket"
  • 使用前缀组织文件（如文件夹）

📖 有关更多故障排除，请参阅 SETUP_GUIDE.md

安全最佳实践

✅ 做：

  • 将凭据存储在 .env file（永远不要提交到git）
  • 使用具有最低所需权限的IAM用户
  • 除非需要，否则禁用ALLOW_WRITE
  • 对预签名的URL使用较短的过期时间
  • 定期旋转访问密钥

❌ 不要：

  • 公开共享预签名URL
  • 使用根AWS帐户凭据
  • 提交 .env 文件到版本控制
  • 授予超出必要范围的权限

项目结构

aws-s3-mcp-server/
├── dist/                 # Compiled JavaScript (generated)
├── src/                  # TypeScript source code
│   ├── index.ts         # Main MCP server
│   └── index.test.ts    # Unit tests
├── examples/            # Example scripts and usage
│   ├── quick-test.js    # AWS connection test
│   ├── test-upload.ps1  # Upload example
│   └── test-download.ps1 # Download example
├── .env.example         # Environment template
├── package.json         # Dependencies
├── tsconfig.json        # TypeScript config
├── README.md           # This file
├── SETUP_GUIDE.md      # Installation guide
└── USAGE_GUIDE.md      # Usage examples

安全

  • AWS凭据仅从环境变量加载
  • 默认情况下，写入操作（预签名的PUT URL）被禁用
  • 所有输入都使用Zod模式进行验证
  • 预签名的URL具有可配置的过期时间（最多7天）
  • 日志被写入stderr，以避免干扰stdio传输

支持

  • 问题： 在GitHub上报告错误或请求功能
  • 安装帮助： 看 SETUP_GUIDE.md
  • 使用帮助： 看 用法_ GIDE.md
  • 示例： 检查 examples/ 目录

贡献

欢迎投稿！拜托：

  1. 分叉存储库
  2. 创建要素分支
  3. 进行更改
  4. 如果适用，添加测试
  5. 提交拉取请求

许可证

麻省理工学院

快速参考

任务 命令
安装 npm install
构建 npm run build
测试AWS node examples/quick-test.js
启动服务器 npm start
运行测试 npm test
发展模式 npm run dev

需要帮助？ 从开始 SETUP_GUIDE.md 用于安装或 用法_ GIDE.md 例如！

相关 MCP