亚马逊S3 MCP

Name: 亚马逊S3 MCP
Author: samuraikun

作者：samuraikun15 星标更新：2025-11-20

安装使用来源：spider==github.com

项目介绍

S3 MCP 服务器

一个提供与 S3 存储桶和对象交互工具的 Amazon S3 Model Context Protocol (MCP) 服务器。

https://github.com/user-attachments/assets/d05ff0f1-e2bf-43b9-8d0c-82605abfb666

功能

🚀 支持的 MCP 传输方式

✅ STDIO 传输 - 直接进程通信用于 Claude Desktop
✅ HTTP 传输 - 带有 Server-Sent Events 的 REST API 用于 Web 客户端
✅ 流式 HTTP - 实时流传输以实现响应式交互

🛠️ 可用工具

✅ list-buckets - 列出可访问的 S3 存储桶（支持过滤）
✅ list-objects - 浏览存储桶中的对象（支持前缀过滤）
✅ get-object - 获取对象内容（支持文本/二进制）

🐳 部署选项

✅ 本地 Node.js - 使用 npm/node 直接执行
✅ Docker CLI - 使用自定义配置进行容器化部署
✅ Docker Compose - 使用 MinIO 进行本地测试的全栈部署
✅ MCP Inspector - 内置调试和测试界面

概述

此 MCP 服务器允许像 Claude 这样的大型语言模型（LLMs）与 AWS S3 存储进行交互。它提供了以下工具：

列出可用的 S3 存储桶
列出存储桶内的对象
获取对象内容

该服务器使用 TypeScript 和 MCP SDK 构建，为 LLMs 提供了一种安全且标准化的方式与 S3 进行接口连接。

安装

先决条件

Node.js 18 或更高版本
npm 或 yarn
配置好 AWS 凭据（通过环境变量或 AWS 凭据文件）
Docker（可选，用于容器化设置）

设置

通过 npm 安装：

# 通过 npm 全局安装
npm install -g aws-s3-mcp

# 或作为项目依赖安装
npm install aws-s3-mcp

如果从源代码构建：

# 克隆仓库
git clone https://github.com/samuraikun/aws-s3-mcp.git
cd aws-s3-mcp

# 安装依赖并构建
npm install
npm run build

配置 AWS 凭据和 S3 访问：

创建一个 .env 文件，包含你的 AWS 配置：

AWS_REGION=us-east-1
S3_BUCKETS=bucket1,bucket2,bucket3
S3_MAX_BUCKETS=5
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key

或者将这些设置为环境变量。

配置

服务器可以通过以下环境变量进行配置：

变量名称	描述	默认值
`AWS_REGION`	你的 S3 存储桶所在的 AWS 区域	`us-east-1`
`S3_BUCKETS`	允许访问的 S3 存储桶名称列表（逗号分隔）	（空）
`S3_MAX_BUCKETS`	列表中返回的最大存储桶数量	`5`
`AWS_ACCESS_KEY_ID`	AWS 访问密钥（如果未使用默认凭据）	（来自 AWS 配置）
`AWS_SECRET_ACCESS_KEY`	AWS 秘密密钥（如果未使用默认凭据）	（来自 AWS 配置）

运行服务器

直接 Node.js 执行

服务器默认使用 HTTP 传输 运行，便于测试和调试：

# 使用 npx（默认 HTTP 传输）
npx aws-s3-mcp

# 如果全局安装（HTTP 传输）
npm install -g aws-s3-mcp
aws-s3-mcp

# 如果从克隆的仓库运行（HTTP 传输）
npm start

# 或直接运行（HTTP 传输）
node dist/index.js

# 显式 HTTP 传输
node dist/index.js --http

# STDIO 传输（用于 Claude Desktop 集成）
node dist/index.js --stdio

当使用 HTTP 传输（默认）时，服务器将在端口 3000 上启动，并提供：

健康检查端点：http://localhost:3000/health
MCP 端点：http://localhost:3000/mcp
SSE 端点：http://localhost:3000/sse

Docker 设置 🐳

你可以使用 Docker CLI 或 Docker Compose 将 S3 MCP 服务器作为 Docker 容器运行。

使用 Docker CLI

构建 Docker 镜像：

docker build -t aws-s3-mcp .

使用环境变量运行容器：

# 方法 1：直接传递环境变量
docker run -d \
  -e AWS_REGION=us-east-1 \
  -e S3_BUCKETS=bucket1,bucket2 \
  -e S3_MAX_BUCKETS=5 \
  -e AWS_ACCESS_KEY_ID=your-access-key \
  -e AWS_SECRET_ACCESS_KEY=your-secret-key \
  --name aws-s3-mcp-server \
  aws-s3-mcp

# 方法 2：使用 .env 文件中的环境变量
docker run -d \
  --env-file .env \
  --name aws-s3-mcp-server \
  aws-s3-mcp

查看容器日志：

docker logs aws-s3-mcp-server

停止并删除容器：

docker stop aws-s3-mcp-server
docker rm aws-s3-mcp-server

注意：对于 HTTP 传输（默认），需要添加 -p 3000:3000 来暴露 HTTP 端口。对于 STDIO 传输（Claude Desktop），不需要端口映射，因为它使用 Docker exec 进行直接通信。

使用 Docker Compose

构建并启动 Docker 容器：

# 构建并启动容器
docker compose up -d s3-mcp

# 查看日志
docker compose logs -f s3-mcp

停止容器：

docker compose down

使用 Docker 和 MinIO 进行测试

Docker Compose 设置包括一个 MinIO 服务用于本地测试：

# 启动 MinIO 和 MCP 服务器
docker compose up -d

# 在 http://localhost:9001 访问 MinIO 控制台
# 默认凭据：minioadmin/minioadmin

MinIO 服务会自动创建两个测试存储桶（test-bucket-1 和 test-bucket-2），并上传示例文件用于测试。

使用 MCP Inspector 调试 🔍

run-inspector.sh 脚本提供了一个简单的方法来使用 MCP Inspector 测试和调试 S3 MCP 服务器。它支持多种传输类型和部署模式。

快速开始

# 显示所有可用选项
./run-inspector.sh --help

# 使用 HTTP 传输（默认）在本地运行
./run-inspector.sh

# 使用 Docker Compose 和 MinIO 进行测试
./run-inspector.sh --docker-compose

传输类型

服务器支持两种传输协议：

HTTP 传输

最佳用途：基于 Web 的调试，外部客户端连接
提供：REST API 端点，Server-Sent Events (SSE)
端口：3000（HTTP），3001+（Inspector UI）

STDIO 传输

最佳用途：直接进程通信，Claude Desktop 集成
提供：标准输入/输出通信
端口：无（直接进程通信）

使用示例

1. 本地开发（HTTP）

# 默认：HTTP 传输用于本地调试
./run-inspector.sh

# 显式 HTTP 传输
./run-inspector.sh --http

这将：

如果需要，构建项目
在端口 3000 上启动带有 HTTP 传输的 MCP 服务器
在浏览器中启动 MCP Inspector
提供端点：
- 健康检查：http://localhost:3000/health
- MCP 端点：http://localhost:3000/mcp
- SSE 端点：http://localhost:3000/sse

2. 本地开发（STDIO）

# STDIO 传输用于本地调试
./run-inspector.sh --stdio

这种模式直接使用标准输入/输出将 MCP Inspector 连接到服务器进程。

3. Docker 与真实 AWS（STDIO）

# 创建 .env 文件并填写你的 AWS 凭据
cp .env.example .env
# 编辑 .env 文件并填写你的 AWS 凭据

# 使用 STDIO 传输（Docker 默认）运行
./run-inspector.sh --docker

这将：

如果需要，构建 Docker 镜像
启动一个带有你 AWS 凭据的容器
通过 Docker exec 连接 MCP Inspector

4. Docker 与真实 AWS（HTTP）

# 使用 HTTP 传输运行
./run-inspector.sh --docker --http

这将：

在端口 3000 上启动容器化的 HTTP 服务器
连接 MCP Inspector 到 HTTP 端点
对于基于 HTTP 的集成测试很有用

5. Docker Compose 与 MinIO（测试）

# 使用 MinIO 进行本地测试（无需 AWS 凭据）
./run-inspector.sh --docker-compose

这将：

启动兼容 S3 的 MinIO 存储
创建测试存储桶：test-bucket-1，test-bucket-2
上传示例文件用于测试
启动连接到 MinIO 的 S3 MCP 服务器
启动 MCP Inspector
在 http://localhost:9001 提供 MinIO Web UI（登录：minioadmin/minioadmin）

高级选项

强制重建

# 强制重新构建 Docker 镜像
./run-inspector.sh --docker --force-rebuild
./run-inspector.sh --docker-compose --force-rebuild

调试技巧

检查容器日志：

# 对于 Docker CLI 模式
docker logs aws-s3-mcp-server

# 对于 Docker Compose 模式
docker compose logs s3-mcp

手动测试端点：

# 健康检查
curl http://localhost:3000/health

# MinIO 健康检查（Docker Compose）
curl http://localhost:9000/minio/health/live

访问 MinIO Web UI（仅限 Docker Compose）：
- URL：http://localhost:9001
- 用户名：minioadmin
- 密码：minioadmin

清理

# 停止并删除 Docker 容器
docker stop aws-s3-mcp-server && docker rm aws-s3-mcp-server

# 停止 Docker Compose 服务
docker compose down

# 停止特定 HTTP 服务器容器
docker stop aws-s3-mcp-http-server && docker rm aws-s3-mcp-http-server

故障排除

端口冲突：如果端口 3000 已被占用，请停止其他服务或更改端口
AWS 凭据：确保你的 .env 文件中有有效的 AWS 凭据（适用于 Docker 模式）
构建错误：使用 --force-rebuild 重新构建 Docker 镜像
连接问题：检查容器是否正在运行，使用 docker ps

快速参考

命令	传输方式	环境	描述
`./run-inspector.sh`	HTTP	本地	使用 HTTP 传输的本地开发
`./run-inspector.sh --stdio`	STDIO	本地	使用 STDIO 传输的本地开发
`./run-inspector.sh --docker`	STDIO	Docker + AWS	使用 AWS 凭据的 Docker 容器
`./run-inspector.sh --docker --http`	HTTP	Docker + AWS	使用 HTTP 传输的 Docker 容器
`./run-inspector.sh --docker-compose`	STDIO	Docker + MinIO	使用 MinIO 进行本地测试（无需 AWS）

连接到 Claude Desktop

要将此服务器与 Claude Desktop 结合使用，你需要使用 STDIO 传输（而不是默认的 HTTP 传输）进行直接进程通信：

编辑你的 Claude Desktop 配置文件：
- macOS：~/Library/Application Support/Claude/claude_desktop_config.json
- Windows：%APPDATA%\Claude\claude_desktop_config.json
将 S3 MCP 服务器添加到配置中：

{
  "mcpServers": {
    "s3": {
      "command": "npx",
      "args": ["aws-s3-mcp", "--stdio"],
      "env": {
        "AWS_REGION": "us-east-1",
        "S3_BUCKETS": "bucket1,bucket2,bucket3",
        "S3_MAX_BUCKETS": "5",
        "AWS_ACCESS_KEY_ID": "your-access-key",
        "AWS_SECRET_ACCESS_KEY": "your-secret-key"
      }
    }
  }
}

Docker 选项用于 Claude Desktop 🐳

你还可以配置 Claude Desktop 使用正在运行的 Docker 容器作为 MCP 服务器：

{
  "mcpServers": {
    "s3": {
      "command": "docker",
      "args": ["exec", "-i", "aws-s3-mcp-server", "node", "dist/index.js"],
      "env": {}
    }
  }
}

⚠️ 重要先决条件：为了使此 Docker 配置生效，你必须首先构建并运行 Docker 容器，然后再启动 Claude Desktop：
# 1. 首先，构建 Docker 镜像（仅需一次或在更改后）
docker build -t aws-s3-mcp .

# 2. 然后启动容器（每次使用前都需要）
# 使用 Docker Compose（推荐）
docker compose up -d s3-mcp

# 或使用 Docker CLI
docker run -d --name aws-s3-mcp-server --env-file .env aws-s3-mcp
如果没有运行的容器，Claude Desktop 在尝试使用 S3 工具时会出现错误。

上面的 Docker 配置使用 exec 将 MCP 请求直接发送到正在运行的容器。由于 Claude 直接与容器通信，因此不需要端口映射。

注意：确保配置中的容器名称（aws-s3-mcp-server）与正在运行的容器名称匹配。

重要：请注意以下几点

替换 AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY 为实际凭据

S3_BUCKETS 应包含你希望允许访问的存储桶的逗号分隔列表

AWS_REGION 应设置为你存储桶所在区域

💣 如果在 Claude Desktop 中遇到错误

如果你在 Claude Desktop 中使用上述配置时遇到错误，请尝试使用绝对路径：

# 获取 node 和 aws-s3-mcp 的路径
which node
which aws-s3-mcp

{
  "globalShortcut": "",
  "mcpServers": {
    "s3": {
      "command": "your-absolute-path-to-node",
      "args": ["your-absolute-path-to-aws-s3-mcp/dist/index.js", "--stdio"],
      "env": {
        "AWS_REGION": "your-aws-region",
        "S3_BUCKETS": "your-s3-buckets",
        "S3_MAX_BUCKETS": "your-max-buckets",
        "AWS_ACCESS_KEY_ID":