S3 MCP 服务器

提供与 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 接口提供了一种安全且标准化的方式。

安装

先决条件

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 工具来执行请求并向您展示结果。

执照

麻省理工学院

You must be authenticated.

security – no known vulnerabilities

license - permissive license

quality - confirmed to work

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Tools

Amazon S3 模型上下文协议服务器允许 Claude 等大型语言模型与 AWS S3 存储交互，提供列出存储桶、列出对象和检索对象内容的工具。

Related MCP Servers

AWS Resources MCP Server
baryhuang
-
security
A
license
-
quality
A Model Context Protocol server that enables Claude to execute Python code using boto3 to query and manage AWS resources directly from conversations.
Last updated -
6
Python
MIT License
AWS MCP Server
rishikavikondala
A
security
A
license
A
quality
A Model Context Protocol server implementation that enables Claude to perform AWS operations on S3 and DynamoDB services through natural language commands.
Last updated -
23
92
Python
MIT License
AWS MCP Server
ihatesea69
-
security
F
license
-
quality
A Model Context Protocol server allowing Claude AI to interact with AWS resources through natural language, enabling users to query and manage AWS services without using the traditional AWS Console or CLI.
Last updated -
TypeScript
Linode MCP Server
komer3
-
security
A
license
-
quality
A Model Context Protocol server that enables Large Language Models like Claude to manage Linode cloud resources, including listing regions, creating, viewing, deleting, and rebooting Linode instances.
Last updated -
Python
MIT License

View all related MCP servers

S3 MCP Server