使用说明

Amazon S3 MCP服务器

用于AWS S3操作的模型上下文协议（MCP）服务器，通过预签名的URL提供对S3存储桶的安全访问。

特性

列出对象：通过前缀过滤和分页浏览S3存储桶内容
下载对象：为安全下载生成有时间限制的预签名URL
上传对象：通过加密和ACL支持，为直接客户端到S3的上传生成预签名URL
删除对象：从S3存储桶中删除对象（具有版本支持）
双格式支持：所有操作都返回Markdown（人类可读）和JSON格式
安全第一：使用预签名的URL来避免凭据暴露，并实现客户端到S3的直接通信
全面验证Pydantic v2模型确保输入验证和类型安全

建筑

此服务器使用 预签名URL 而不是直接上传/下载，有几个关键好处：

安全：不暴露AWS凭据的限时访问
可扩展性：直接客户端到S3通信（无服务器瓶颈）
演出：消除了服务器作为数据传输的中介
灵活性：适用于任何HTTP客户端（浏览器、curl等）

先决条件

python：3.10或更高
AWS帐户：具有S3访问权限
AWS凭据：通过AWS CLI、环境变量或IAM角色配置
紫外线 （可选）：快速Python包管理器- 安装UV

安装

1.克隆或下载

cd /path/to/mcp-servers/aws-s3-mcp

2.安装依赖项

选项A：使用pip（传统）

# Install in development mode
pip install -e .

# Or install with dev dependencies for testing
pip install -e ".[dev]"

选项B：使用UV（建议用于Claude Desktop）

# Install UV first (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies with UV
uv sync

# Or install with dev dependencies
uv sync --all-extras

3.配置AWS凭据

选择以下方法之一：

选项A:AWS CLI（建议用于开发）

aws configure

选项B：环境变量

export AWS_ACCESS_KEY_ID=your-access-key
export AWS_SECRET_ACCESS_KEY=your-secret-key
export AWS_REGION=us-east-1

选项C：命名配置文件

# Create .env file
cp .env.example .env

# Edit .env and set:
# AWS_PROFILE=my-profile
# AWS_REGION=us-east-1

用法

运行服务器

使用Python

# Run directly as module
python -m s3_mcp

# Or use the installed command
s3-mcp

使用UV

# Run with UV
uv run s3-mcp

# Or run from specific directory
uv --directory /path/to/mcp-servers/aws-s3-mcp run s3-mcp

# Or use UVX (tool runner)
uvx --from /path/to/mcp-servers/aws-s3-mcp s3-mcp

Claude桌面配置

添加到您的Claude Desktop配置文件中：

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json

选项1：使用Python（传统）

{
  "mcpServers": {
    "s3": {
      "command": "python",
      "args": ["-m", "s3_mcp"],
      "env": {
        "AWS_REGION": "us-east-1",
        "AWS_PROFILE": "default"
      }
    }
  }
}

选项2：将UV与目录路径一起使用

{
  "mcpServers": {
    "s3": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-servers/aws-s3-mcp",
        "run",
        "s3-mcp"
      ],
      "env": {
        "AWS_REGION": "us-east-1",
        "AWS_PROFILE": "default"
      }
    }
  }
}

选项3：使用UVX（UV工具运行器）

{
  "mcpServers": {
    "s3": {
      "command": "uvx",
      "args": [
        "--from",
        "/path/to/mcp-servers/aws-s3-mcp",
        "s3-mcp"
      ],
      "env": {
        "AWS_REGION": "us-east-1",
        "AWS_PROFILE": "default"
      }
    }
  }
}

选项4：使用项目目录中的UV

{
  "mcpServers": {
    "s3": {
      "command": "uv",
      "args": ["run", "s3-mcp"],
      "cwd": "/path/to/mcp-servers/aws-s3-mcp",
      "env": {
        "AWS_REGION": "us-east-1",
        "AWS_PROFILE": "default"
      }
    }
  }
}

备注：替换 /path/to/mcp-servers/aws-s3-mcp 使用安装目录的实际绝对路径。

我应该使用哪个选项？

选项1（Python）：最好是全局安装Python，并使用pip安装软件包
选项2（带--目录的UV）：最适合开发，保持每个项目的依赖关系隔离
选项3（UVX）：最适合快速执行工具，自动处理依赖关系
选项4（UV与cwd）：备选方案2，使用 cwd 而不是 --directory

推荐：使用 选项2 或 选项3 UV可实现更好的依赖隔离和更快的启动时间。

可用工具

1. `s3_list_objects`

列出S3存储桶中的对象，并可选择前缀过滤和分页。

参数：

bucket_name （必填）：S3存储桶名称（3-63个字符，小写）
prefix （可选）：按键前缀过滤对象（例如，“logs/2024/”）
limit （可选）：要返回的最大对象数（1-1000，默认值：20）
continuation_token （可选）：来自先前响应的标记，用于分页
response_format （可选）：“markdown”（默认）或“json”

例子：

List objects in my-data-bucket with prefix "images/"

答复包括：

对象键、大小、上次修改日期、存储类
分页标记（如果存在更多结果）

2. `s3_get_object`

生成用于下载S3对象的预签名URL。

参数：

bucket_name （必填）：S3存储桶名称
key （必填）：对象键（bucket内的路径）
expires_in （可选）：URL过期时间（秒）（1-604800，默认值：3600）
response_content_disposition （可选）：覆盖内容处置标头
response_content_type （可选）：覆盖Content-Type标头
response_format （可选）：“markdown”（默认）或“json”

例子：

Generate download URL for my-data-bucket/reports/2024-report.pdf

答复包括：

限时预签名URL（在指定持续时间内有效）
到期时间戳
使用示例（curl命令）

安全说明：

URL有时间限制（最多7天，默认1小时）
任何拥有该URL的人都可以在有效期内下载
URL在过期之前不能撤销

3. `s3_put_object`

生成一个预签名的URL，用于将对象上传到S3。

参数：

bucket_name （必填）：S3存储桶名称
key （必填）：目标对象键
expires_in （可选）：URL过期时间（秒）（1-604800，默认值：3600）
content_type （可选）：MIME类型（例如，“image/png”、“application/pdf”）
server_side_encryption （可选）：“AES256”或“aws:kms”
metadata （可选）：自定义元数据作为键值对
acl （可选）：访问控制（“私有”、“公共读取”等）
response_format （可选）：“markdown”（默认）或“json”

例子：

Generate upload URL for my-bucket/uploads/document.pdf with encryption

答复包括：

PUT操作的预签名URL
所需的标头（内容类型、加密等）
用法示例（带有所有必需标头的curl命令）

安全说明：

使用强制加密 server_side_encryption 参数
除非需要公共访问，否则使用“私有”ACL
URL的作用域为特定的对象键

4. `s3_delete_object`

从S3存储桶中删除对象。

⚠️ 警告：这是一次破坏性行动。除非启用版本控制，否则无法恢复已删除的对象。

参数：

bucket_name （必填）：S3存储桶名称
key （必填）：要删除的对象键
version_id （可选）：要删除的特定版本（用于版本化桶）
response_format （可选）：“markdown”（默认）或“json”

例子：

Delete my-bucket/temp/old-file.txt

行为：

无版本控制的bucket：对象被永久删除
版本化桶：删除已创建的标记（对象可以恢复）
带有version_id：永久删除特定版本

答复包括：

删除确认
版本信息（如适用）

发展

Makefile快速入门

该项目包括一个用于常见开发任务的Makefile：

make help         # Show all available commands
make install-dev  # Install package with dev dependencies
make test         # Run test suite
make test-cov     # Run tests with coverage report
make lint         # Check code quality
make format       # Format code
make check        # Run all checks (lint + typecheck + test)
make inspector    # Launch MCP Inspector for testing
make clean        # Remove build artifacts

项目结构

aws-s3-mcp/
├── s3_mcp/
│   ├── __init__.py          # Package initialization
│   ├── __main__.py          # Entry point
│   ├── server.py            # FastMCP server and tool definitions
│   └── s3/
│       ├── __init__.py      # S3 module exports
│       ├── client.py        # S3 client wrapper with error handling
│       ├── operations.py    # Core business logic for all operations
│       └── utils.py         # Shared utilities and formatters
├── tests/                   # Test suite (pytest + moto)
├── pyproject.toml          # Project configuration and dependencies
├── .env.example            # Example environment configuration
└── README.md               # This file

运行测试

# Using Makefile (recommended)
make install-dev  # Install with dev dependencies
make test         # Run tests
make test-cov     # Run tests with coverage report

# Or use pytest directly
pip install -e ".[dev]"
pytest -v
pytest --cov=s3_mcp --cov-report=html

测试套件：

✅ 涵盖所有操作的50个单元测试
✅ 核心业务逻辑（operations.py）的覆盖率达到95%
✅ 88%的公用事业覆盖率（utils.py）
✅ 测试包括：列表对象、获取/放置/删除操作、分页、错误处理、版本控制、加密、ACL

MCP检验员测试

使用MCP检查器交互式测试服务器：

# Using Makefile
make inspector

# Or run directly
npx @modelcontextprotocol/inspector python -m s3_mcp.server

这将：

启动MCP检查器web界面
启动S3 MCP服务器
打开一个浏览器，您可以在其中测试所有工具
查看工具模式，使用不同参数进行测试，并检查响应

代码质量

# Using Makefile (recommended)
make format      # Format code with ruff
make lint        # Check code with ruff
make typecheck   # Run mypy type checking
make check       # Run all checks (lint + typecheck + test)

# Or run tools directly
ruff format .
ruff check .
mypy s3_mcp/

配置

环境变量

创建一个 .env 文件来自 .env.example:

# AWS Region (default: us-east-1)
AWS_REGION=us-east-1

# AWS Profile (optional)
AWS_PROFILE=my-profile

# Maximum Presigned URL Expiration (optional, default: 604800 seconds = 7 days)
MAX_PRESIGNED_URL_EXPIRATION=604800

AWS IAM权限

服务器需要以下IAM权限：

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:ListBucket",
        "s3:GetObject",
        "s3:PutObject",
        "s3:DeleteObject"
      ],
      "Resource": [
        "arn:aws:s3:::your-bucket-name",
        "arn:aws:s3:::your-bucket-name/*"
      ]
    }
  ]
}

对于版本化桶，还添加：

{
  "Effect": "Allow",
  "Action": [
    "s3:DeleteObjectVersion",
    "s3:GetObjectVersion"
  ],
  "Resource": "arn:aws:s3:::your-bucket-name/*"
}

安全最佳实践

预先签名的URL

使用短过期时间 敏感数据（分钟，而非小时）
监视URL生成 在CloudTrail日志中
验证存储桶策略 防止未经授权的预签名URL生成
考虑VPC端点 用于私人S3访问

AWS凭据

从不提交凭据 到版本控制
使用IAM角色 生产中（EC2、ECS、Lambda）
旋转访问键 经常
使用最小权限 IAM权限
启用MFA 用于敏感操作

数据保护

启用加密 默认情况下（使用 server_side_encryption 参数）
启用版本控制 用于重要水桶
配置生命周期策略 用于自动化数据管理
启用访问日志记录 用于审计跟踪

故障排除

常见问题

问题: ImportError: No module named 'fastmcp'

解决方案：运行 pip install -e . 安装依赖项

问题: NoCredentialsError: Unable to locate credentials

解决方案：使用配置AWS凭据 aws configure 或环境变量

问题: AccessDenied: Access Denied

解决方案：验证您尝试的S3操作的IAM权限

问题: NoSuchBucket: The specified bucket does not exist

解决方案：验证存储桶名称和区域配置

问题：预签名的URL返回403 Forbidden

解决方案：检查：
- 包括所需的标题（用于PUT操作）
- URL尚未过期
- Bucket策略允许操作

调试

启用调试日志记录：

import logging
logging.basicConfig(level=logging.DEBUG)

贡献

欢迎投稿！拜托：

分叉存储库
创建要素分支
通过测试进行更改
运行代码质量检查(black, ruff, pytest)
提交拉取请求

许可证

该项目根据MIT许可证获得许可。

支持

对于问题、疑问或贡献：

在GitHub上打开一个问题
检查现有问题的解决方案
针对API特定问题，查看AWS S3文档

使用说明

Amazon S3 MCP服务器

特性

建筑

先决条件

安装

1.克隆或下载

2.安装依赖项

选项A：使用pip（传统）

选项B：使用UV（建议用于Claude Desktop）

3.配置AWS凭据

用法

运行服务器

使用Python

使用UV

Claude桌面配置

选项1：使用Python（传统）

选项2：将UV与目录路径一起使用

选项3：使用UVX（UV工具运行器）

选项4：使用项目目录中的UV

我应该使用哪个选项？

可用工具

1. s3_list_objects

2. s3_get_object

3. s3_put_object

4. s3_delete_object

发展

Makefile快速入门

项目结构

运行测试

MCP检验员测试

代码质量

配置

环境变量

AWS IAM权限

安全最佳实践

预先签名的URL

AWS凭据

数据保护

故障排除

常见问题

调试

贡献

许可证

相关资源

支持

相关 MCP

加密秘密链接服务

S3存储桶列表工具

图表生成服务

Wasabi 云存储 MCP 服务器

加密笔记服务

S3图片上传服务

1. `s3_list_objects`

2. `s3_get_object`

3. `s3_put_object`

4. `s3_delete_object`