S3 MCP 服务器

Name: S3 MCP Server
Author: samuraikun

琐事扫描 npm 版本 npm 下载许可证：MIT Node.js 版本

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

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

概述

此 MCP 服务器允许 Claude 等大型语言模型 (LLM) 与 AWS S3 存储进行交互。它提供以下工具：

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

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

Related MCP server: AWS MCP Server

安装

先决条件

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

设置

通过 npm 安装：

# Install globally via npm npm install -g aws-s3-mcp # Or as a dependency in your project npm install aws-s3-mcp

如果从源代码构建：

# 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

配置 AWS 凭证和 S3 访问：

使用您的 AWS 配置创建一个.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

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

配置

可以使用以下环境变量配置服务器：

多变的	描述	默认
`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

您可以直接使用 Node.js 运行服务器：

# Using npx (without installing) npx aws-s3-mcp # If installed globally npm install -g aws-s3-mcp aws-s3-mcp # If running from cloned repository npm start # Or directly node dist/index.js

Docker 设置🐳

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

使用 Docker CLI

构建 Docker 镜像：

docker build -t aws-s3-mcp .

使用环境变量运行容器：

# 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

检查容器日志：

docker logs aws-s3-mcp-server

停止并删除容器：

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

请注意，该容器不会公开任何端口，因为它设计为通过 Docker exec 而不是直接 HTTP 连接与 Claude Desktop 一起使用。

使用 Docker Compose

构建并启动 Docker 容器：

# Build and start the container docker compose up -d s3-mcp # View logs docker compose logs -f s3-mcp

要停止容器：

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 服务会自动创建两个测试 bucket（ test-bucket-1和test-bucket-2 ）并上传测试用的示例文件。

在 MCP Inspector 上调试

要使用 MCP Inspector 调试服务器：

# Run inspector with local Node.js sh run-inspector.sh # Run inspector with Docker Compose and MinIO sh run-inspector.sh --docker-compose # Run inspector with Docker CLI (without Docker Compose) sh run-inspector.sh --docker

当使用--docker-compose选项时，脚本将：

如果 MinIO 和 S3 MCP 服务器容器未运行，请启动它们
启动连接到 S3 MCP 服务器的 MCP 检查器
然后，您可以针对本地 MinIO 实例测试 S3 工具

连接到 Claude Desktop

要将此服务器与 Claude Desktop 一起使用：

编辑您的 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"], "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 Desktop 的 Docker 选项🐳

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

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

⚠️ 重要先决条件：要使此 Docker 配置正常工作，您必须在启动 Claude Desktop之前先构建并运行 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 出现错误

如果在 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"], "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" } } } }

可用工具

列表桶

列出服务器有权访问的可用 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 bucket 的名称
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 bucket 的名称
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 文件”
“从 my-documents-bucket 获取 README.txt 文件”

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

执照

麻省理工学院

S3 MCP Server