S3 MCP Server

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 - 实时流式传输，带来灵敏的交互体验

🛠️ 可用工具

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

🐳 部署选项

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

概述

此 MCP 服务允许 Claude 等大模型与 AWS S3 存储交互。它提供以下工具：

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

此服务使用 TypeScript 和 MCP SDK 构建，为大模型提供了一种安全且标准化的方式来与 S3 交互。

安装

前置条件

• Node.js 18 或更高版本
• npm 或 yarn
• 已配置 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

2. 如果从源代码构建：

# 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

3. 配置 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 .

2. 使用环境变量运行容器：

# 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

3. 查看容器日志：

docker logs aws-s3-mcp-server

4. 停止并移除容器：

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

2. 停止容器：

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 Inspector 调试 🔍

run-inspector.sh 脚本提供了一种简单的方法，可使用 MCP Inspector 测试和调试 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+（Inspector 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 Inspector
• 提供以下端点：
  • 健康检查：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 Inspector 直接连接到服务进程。

3. 使用真实 AWS 的 Docker（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 Inspector

4. 使用真实 AWS 的 Docker（HTTP）

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

这将：

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

5. 使用 MinIO 的 Docker Compose（测试）

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

这将：

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

高级选项

强制重新构建

# 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）：

   • URL：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 文件中包含有效的 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 传输）进行进程间直接通信：

1. 编辑 Claude Desktop 配置文件：

   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%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 Desktop 的 Docker 选项 🐳

你也可以配置 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. 然后启动容器（每次在 Claude 中使用前都必须启动）
# 使用 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 中使用上述配置时遇到错误，请尝试使用绝对路径，如下所示：

# 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"
      }
    }
  }
}

可用工具

list-buckets

列出服务有权访问的 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"
  }
]

list-objects

列出指定 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"
  }
]

get-object

从指定的 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 存储桶”
• “总结 my-documents-bucket 中的 PDF 文件”
• “获取 my-documents-bucket 中的 README.txt 文件”

Claude 会使用相应的 MCP 工具执行请求，并向你显示结果。

许可证

MIT