MCP S3

🚀 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