🚀 MCP S3文件管理器
MCP S3文件管理器可通过模型上下文协议（MCP）在亚马逊S3中上传、下载和管理文件，为AI工作流提供便捷的S3文件操作。它适用于Claude、Cursor等AI助手以及任何与MCP兼容的客户端。
🚀 快速开始
# 安装并运行（需要AWS凭证）
uvx mcp-s3 --root ~/uploads
# 或者全局安装
pip install mcp-s3
✨ 主要特性
- 文件操作丰富：支持文件的上传、下载、列表查看和信息获取等操作。
- 安全可靠：防止目录遍历攻击，使用环境变量管理凭证，预签名URL有时间限制，可检测文件冲突。
- 使用便捷：保留原始文件名，可防止意外覆盖，支持强制覆盖选项，大文件支持进度跟踪。
📦 安装指南
运行而不安装（推荐）
uvx mcp-s3
全局安装
pip install mcp-s3
开发安装
git clone && uv sync
💻 使用示例
基础用法
上传文件
@mcp Upload my config.json file to S3
@mcp Upload the backup.zip with 2-hour expiration
@mcp Upload report.pdf with force overwrite enabled
下载文件
@mcp Download config.json from S3 to ./downloads/
@mcp Download backup-2024.zip from S3
列出文件
@mcp List all files in S3
@mcp List files starting with "logs/"
@mcp Show me the first 50 files in the bucket
获取文件信息
@mcp Get info about config.json in S3
@mcp Show details for backup.zip
高级用法
备份和共享代码
# 上传项目文件
@mcp Upload my entire src/ directory to S3
@mcp Generate a 7-day URL for team-config.json
CI/CD集成
# 在部署脚本中
mcp-s3 --root ./build upload dist.tar.gz
日志管理
# 上传应用程序日志
@mcp Upload today's error.log to S3
@mcp List all log files from this month
资产管理
# 管理项目资产
@mcp Upload design-assets.zip
@mcp Download latest-assets.zip to ./assets/
📚 详细文档
1. AWS凭证设置
在项目中创建.env文件：
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
AWS_DEFAULT_REGION=us-east-1
S3_BUCKET_NAME=your-bucket-name
2. 添加到AI工具
Cursor IDE
添加到settings.json：
{
"mcp": {
"servers": {
"s3": {
"command": "uvx",
"args": ["mcp-s3", "--root", "~/uploads"],
"env": {
"AWS_ACCESS_KEY_ID": "your_key",
"AWS_SECRET_ACCESS_KEY": "your_secret",
"S3_BUCKET_NAME": "your-bucket"
}
}
}
}
}
Claude Desktop
添加到配置文件：
{
"mcpServers": {
"s3": {
"command": "mcp-s3",
"args": ["--root", "~/uploads"],
"env": {
"AWS_ACCESS_KEY_ID": "your_key",
"AWS_SECRET_ACCESS_KEY": "your_secret",
"S3_BUCKET_NAME": "your-bucket"
}
}
}
}
开发设置
git clone https://github.com/dayongd1/mcp-s3.git
cd mcp-s3
uv sync
uv run mcp-s3 --root ~/test-uploads
测试
# 测试基本功能
python examples/test_mcp_server.py
# 测试命名冲突
python examples/test_naming_conflicts.py
# 测试所有功能
python examples/test_download.py
python examples/test_list_files.py
python examples/test_get_file_info.py
🔧 技术细节
- 路径安全：防止目录遍历攻击。
- 凭证管理：使用环境变量管理凭证，避免硬编码密钥。
- 预签名URL：默认提供24小时的限时访问。
- 冲突检测：防止意外覆盖文件。
🚫 故障排除
"Bucket not found"
# 检查桶名称和区域
aws s3 ls s3://your-bucket-name
"Access denied"
# 验证AWS凭证
python examples/test_aws_connection.py
"File already exists"
# 使用强制覆盖或重命名文件
@mcp Upload config.json with force overwrite enabled
📄 许可证
本项目采用MIT许可证。
📚 链接
- PyPI：https://pypi.org/project/mcp-s3/
- GitHub：https://github.com/dayongd1/mcp-s3
- MCP文档：https://modelcontextprotocol.io/
- AWS S3设置：请参阅
AWS_SETUP_GUIDE.md