星战科技xingzhan.cloud
返回市场
AWS-S3-MCP-服务器

AWS-S3-MCP-服务器

作者：khuynh222 星标更新：2025-11-02
安装使用来源：spider==github.com

项目介绍

AWS S3 MCP 服务器

这是一个通过安全且定义良好的接口暴露 AWS S3 操作的模型上下文协议（MCP）服务器。该服务器提供了列出存储桶和对象以及生成预签名 URL 的工具，以确保数据访问的安全性。

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

功能

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

🚀 快速开始

最快速设置

# 1. 安装并构建
npm install
npm run build

# 2. 配置 AWS 凭证
cp .env.example .env
# 编辑 .env 文件，填写您的 AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION

# 3. 测试连接
node examples/quick-test.js

4. 添加到您的 MCP 客户端

对于 Claude Desktop - 编辑 claude_desktop_config.json：

{
  "mcpServers": {
    "aws-s3": {
      "command": "node",
      "args": ["/绝对路径到/aws-s3-mcp-server/dist/index.js"]
    }
  }
}

对于 VS Code - 编辑 ~/.vscode/mcp.json：

{
  "servers": {
    "aws-s3": {
      "type": "stdio",
      "command": "node",
      "args": ["/绝对路径到/aws-s3-mcp-server/dist/index.js"]
    }
  }
}

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

5. 测试它

  • Claude Desktop: 重启 → 请求“列出我的 S3 存储桶”
  • VS Code: 重新加载窗口 → @aws-s3 列出我的存储桶

📖 完整指南: QUICKSTART.md

文档

安装

npm install
npm run build

配置

在根目录创建一个 .env 文件（参考 .env.example）：

# 必需
AWS_ACCESS_KEY_ID=您的访问密钥
AWS_SECRET_ACCESS_KEY=您的秘密密钥
AWS_REGION=us-east-1

# 可选：启用写操作（presign_put）
ALLOW_WRITE=false

# 可选：设置日志级别（默认：info）
LOG_LEVEL=info

📖 详细的安装说明，请参阅 SETUP_GUIDE.md

使用

该服务器使用标准输入输出传输，并通过标准输入输出进行通信，使其适合与像 Claude Desktop 这样的 MCP 客户端集成。

单独运行

npm start

常见操作

列出所有存储桶：

"显示我所有的 S3 存储桶"

列出存储桶中的对象：

"列出 my-data-bucket 中的所有文件"

获取下载链接：

"给我 my-docs-bucket 中 report.pdf 的下载链接"

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

"生成 my-bucket 中 new-file.json 的上传 URL"

📖 完整的使用示例，请参阅 USAGE_GUIDE.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-0-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. 查看 Claude Desktop 日志：帮助 → 显示日志
  2. 验证配置中的服务器路径是否正确（使用绝对路径）
  3. 手动测试：node dist/index.js
  4. 重启 Claude Desktop

AWS 连接问题

错误：缺少凭证

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

错误：访问被拒绝

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

错误：无效的访问密钥

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

写操作不起作用

  • 在 .env 文件中设置 ALLOW_WRITE=true
  • 重启 MCP 服务器
  • 验证 IAM 用户具有 PutObject 权限

性能问题

对于包含数百万对象的存储桶：

  • 使用前缀过滤："列出 my-bucket 中带有前缀 'logs/2024/' 的文件"
  • 限制结果数量："显示 my-bucket 中的前 100 个文件"
  • 使用前缀组织文件（类似于文件夹）

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

安全最佳实践

✅ 应该做：

  • 将凭证存储在 .env 文件中（不要提交到 Git）
  • 使用具有最小必要权限的 IAM 用户
  • 默认禁用 ALLOW_WRITE
  • 使用较短的过期时间来生成预签名 URL
  • 定期轮换访问密钥

❌ 不应该做：

  • 公开分享预签名 URL
  • 使用 AWS 根账户凭证
  • 将 .env 文件提交到版本控制
  • 授予比必要的更广泛的权限

项目结构

aws-s3-mcp-server/
├── dist/                 # 编译后的 JavaScript（生成）
├── src/                  # TypeScript 源代码
│   ├── index.ts         # 主 MCP 服务器
│   └── index.test.ts    # 单元测试
├── examples/            # 示例脚本和使用
│   ├── quick-test.js    # AWS 连接测试
│   ├── test-upload.ps1  # 上传示例
│   └── test-download.ps1 # 下载示例
├── .env.example         # 环境模板
├── package.json         # 依赖项
├── tsconfig.json        # TypeScript 配置
├── README.md           # 本文件
├── SETUP_GUIDE.md      # 安装指南
└── USAGE_GUIDE.md      # 使用示例

安全

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

支持

  • 问题：在 GitHub 上报告 bug 或请求功能
  • 安装帮助：参阅 SETUP_GUIDE.md
  • 使用帮助：参阅 USAGE_GUIDE.md
  • 示例：查看 examples/ 目录

贡献

欢迎贡献！请：

  1. 分叉仓库
  2. 创建功能分支
  3. 进行更改
  4. 如果适用，添加测试
  5. 提交合并请求

许可

MIT

快速参考

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

需要帮助？ 从 SETUP_GUIDE.md 开始安装或从 USAGE_GUIDE.md 获取示例！