AI导哈

S3存储交互服务

一个提供与AWS S3存储桶和对象交互工具的MCP服务器，适用于大型语言模型如Claude进行S3操作。

  • by samuraikun
  • TypeScript
  • 本地部署
  • 30 星标
  • 更新于
在 GitHub 查看 samuraikun/aws-s3-mcp

使用说明

S3 MCP服务器

Amazon S3模型上下文协议（MCP）服务器，提供与S3存储桶和对象交互的工具。

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

特性

🚀 MCP传输支持

  • ✅ STDIO传输 -Claude Desktop的直接进程通信
  • ✅ HTTP传输 -用于web客户端的带有服务器端事件的REST API
  • ✅ 流式HTTP -实时流媒体，实现响应式交互

🛠️ 可用工具

  • ✅ 列出bucket -列出可访问的S3存储桶并进行筛选
  • ✅ 列出对象 -使用前缀过滤浏览bucket中的对象
  • ✅ 获取对象 -检索对象内容（文本/二进制支持）

🐳 部署选项

  • ✅ 本地Node.js -使用npm/node直接执行
  • ✅ Docker命令行界面 -具有自定义配置的容器化部署
  • ✅ Docker Compose -全栈MinIO用于本地测试
  • ✅ MCP检查员 -内置调试测试界面

概述

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

  • 列出可用的S3存储桶
  • 列出bucket中的对象
  • 检索对象内容

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

安装

先决条件

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

设置

  1. 通过npm安装：
# Install globally via npm
npm install -g aws-s3-mcp

# Or as a dependency in your project
npm install aws-s3-mcp
  1. 如果从源构建：
# Clone the repository
git clone https://github.com/samuraikun/aws-s3-mcp.git
cd aws-s3-mcp

# Install dependencies and build
npm install
npm run build
  1. 配置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传输，使测试和调试变得容易：

# Using npx (HTTP transport by default)
npx aws-s3-mcp

# If installed globally (HTTP transport)
npm install -g aws-s3-mcp
aws-s3-mcp

# If running from cloned repository (HTTP transport)
npm start

# Or directly (HTTP transport)
node dist/index.js

# Explicit HTTP transport
node dist/index.js --http

# STDIO transport (for Claude Desktop integration)
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

  1. 构建Docker镜像：
docker build -t aws-s3-mcp .
  1. 使用环境变量运行容器：
# Option 1: Pass environment variables directly
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

# Option 2: Use environment variables from .env file
docker run -d \
  --env-file .env \
  --name aws-s3-mcp-server \
  aws-s3-mcp
  1. 检查容器日志：
docker logs aws-s3-mcp-server
  1. 停止并移除容器：
docker stop aws-s3-mcp-server
docker rm aws-s3-mcp-server

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

使用Docker Compose

  1. 构建并启动Docker容器：
# Build and start the container
docker compose up -d s3-mcp

# View logs
docker compose logs -f s3-mcp
  1. 要停止容器：
docker compose down

使用Docker和MinIO进行测试

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

# Start MinIO and the MCP server
docker compose up -d

# Access MinIO console at http://localhost:9001
# Default credentials: minioadmin/minioadmin

MinIO服务自动创建两个测试桶(test-bucket-1 和 test-bucket-2)并上传样本文件进行测试。

使用MCP检查器进行调试🔍

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

快速开始

# Show all available options
./run-inspector.sh --help

# Run locally with HTTP transport (default)
./run-inspector.sh

# Run with Docker Compose and MinIO for testing
./run-inspector.sh --docker-compose

运输类型

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

HTTP传输

  • 最适合：基于Web的调试，外部客户端连接
  • 提供：REST API端点，服务器端事件（SSE）
  • 港口：3000（HTTP），3001+（检查器UI）

STDIO传输

  • 最适合：直接流程通信，Claude Desktop集成
  • 提供：标准输入/输出通信
  • 港口：无（直接过程沟通）

使用示例

1.本地开发（HTTP）

# Default: HTTP transport for local debugging
./run-inspector.sh

# Explicit HTTP transport
./run-inspector.sh --http

这将：

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

2.地方发展（STDIO）

# STDIO transport for local debugging
./run-inspector.sh --stdio

此模式使用标准输入/输出将MCP检查器直接连接到服务器进程。

3.Docker与真实AWS（STDIO）

# Create .env file with your AWS credentials
cp .env.example .env
# Edit .env with your AWS credentials

# Run with Docker using STDIO transport (default for Docker)
./run-inspector.sh --docker

这将：

  • 如果需要，构建Docker镜像
  • 使用您的AWS凭据启动容器
  • 通过Docker exec连接MCP检查器

4.Docker与真正的AWS（HTTP）

# Run with Docker using HTTP transport
./run-inspector.sh --docker --http

这将：

  • 在端口3000上启动容器化HTTP服务器
  • 将MCP检查器连接到HTTP端点
  • 可用于测试基于HTTP的集成

5.使用MinIO编写Docker（测试）

# Run with MinIO for local testing (no AWS credentials needed)
./run-inspector.sh --docker-compose

这将：

  • 启动MinIO S3兼容存储
  • 创建测试桶： test-bucket-1, test-bucket-2
  • 上传示例文件进行测试
  • 启动连接到MinIO的S3 MCP服务器
  • 启动MCP检查器
  • 在以下位置提供MinIO Web UI http://localhost:9001 （登录：迷你显示器/迷你显示器）

高级选项

强制重建

# Force Docker image rebuild
./run-inspector.sh --docker --force-rebuild
./run-inspector.sh --docker-compose --force-rebuild

调试提示

  1. 检查容器日志:

    # For Docker CLI mode
docker logs aws-s3-mcp-server

# For Docker Compose mode
docker compose logs s3-mcp

  2. 手动测试端点:

    # Health check
curl http://localhost:3000/health

# MinIO health (Docker Compose)
curl http://localhost:9000/minio/health/live

  3. 访问MinIO Web UI （仅限Docker Compose）：

    • 网址： http://localhost:9001
    • 用户名： minioadmin
    • 密码： minioadmin

清理

# Stop and remove Docker containers
docker stop aws-s3-mcp-server && docker rm aws-s3-mcp-server

# Stop Docker Compose services
docker compose down

# Stop specific HTTP server container
docker stop aws-s3-mcp-http-server && docker rm aws-s3-mcp-http-server

故障排除

  • 端口冲突：如果端口3000正在使用中，请停止其他服务或更改端口
  • AWS凭据：确保您的 .env 文件具有适用于Docker模式的有效AWS凭据
  • 构建错误：使用 --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一起使用，您需要使用 STDIO传输 （不是默认的HTTP传输）用于直接进程通信：

  1. 编辑您的Claude Desktop配置文件：

    • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
    • 窗户： %APPDATA%\Claude\claude_desktop_config.json

  2. 将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"
      }
    }
  }
}

Claude桌面版的Docker选项🐳

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

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

⚠️ 重要先决条件：要使此Docker配置工作，您 必须 首先构建并运行Docker容器 之前 启动克劳德桌面：

# 1. First, build the Docker image (only needed once or after changes)
docker build -t aws-s3-mcp .

# 2. Then start the container (required each time before using with Claude)
# Using Docker Compose (recommended)
docker compose up -d s3-mcp

# Or using 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中遇到上述配置错误，请尝试使用以下绝对路径：

# Get the path of node and 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": "your-access-key",
        "AWS_SECRET_ACCESS_KEY": "your-secret-key"
      }
    }
  }
}

可用工具

列出bucket

列出服务器有权访问的可用S3存储桶。此工具尊重 S3_BUCKETS 限制显示哪些桶的配置。

参数： 无

输出示例：

[
  {
    "Name": "my-images-bucket",
    "CreationDate": "2022-03-15T10:30:00.000Z"
  },
  {
    "Name": "my-documents-bucket",
    "CreationDate": "2023-05-20T14:45:00.000Z"
  }
]

列出对象

列出指定S3存储桶中的对象。

参数：

  • bucket （必填）：用于列出对象的S3存储桶的名称
  • prefix （可选）：过滤对象的前缀（如文件夹路径）
  • maxKeys （可选）：要返回的最大对象数

输出示例：

[
  {
    "Key": "sample.pdf",
    "LastModified": "2023-10-10T08:12:15.000Z",
    "Size": 2048576,
    "StorageClass": "STANDARD"
  },
  {
    "Key": "sample.md",
    "LastModified": "2023-10-12T15:30:45.000Z",
    "Size": 1536000,
    "StorageClass": "STANDARD"
  }
]

获取对象

从指定的S3存储桶中检索对象。文本文件以纯文本形式返回，而二进制文件返回的细节有限。

参数：

  • bucket （必填）：S3存储桶的名称
  • key （必填）：要检索的对象的键（路径）

示例文本输出：

This is the content of a text file stored in S3.
It could be JSON, TXT, CSV or other text-based formats.

二进制输出示例：

Binary content (image/jpeg): base64 data is /9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRof...

安全考虑

  • 服务器将仅访问 S3_BUCKETS 环境变量
  • AWS凭据必须具有对存储桶的适当权限
  • 配置AWS权限时使用最小权限原则
  • 对于生产用途，考虑使用具有特定S3权限的IAM角色

与Claude一起使用

在桌面应用程序中与Claude交互时，您可以要求它执行S3操作，例如：

  • “列出我的所有S3存储桶”
  • “汇总我的文档桶中的PDF文件”
  • “从我的文档桶中获取README.txt文件”

Claude将使用适当的MCP工具执行请求并向您展示结果。

许可证

麻省理工学院

相关 MCP