MCP S3

🚀 MCP S3 File Manager

AIワークフロー向けのS3ファイル操作 - Model Context Protocol (MCP) を通じて、Amazon S3内のファイルのアップロード、ダウンロード、管理を行います。

ClaudeやCursorなどのAIアシスタントや、MCP対応のクライアントに最適です。

🚀 クイックスタート

# インストールして実行（AWSの認証情報が必要）
uvx mcp-s3 --root ~/uploads

# またはグローバルにインストール
pip install mcp-s3

💻 使用例

基本的な使用法

# インストールと実行
uvx mcp-s3 --root ~/uploads

高度な使用法

# グローバルにインストール
pip install mcp-s3

🔧 設定

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

✨ 主な機能

ファイルのアップロード

@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

• 元のファイル名を保持 (config.json → config.json)
• 誤った上書きを防止 (ファイルが存在する場合は失敗)
• 強制上書きオプション 意図的な置き換え用
• 大きなファイルの進捗追跡

ファイルのダウンロード

@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

🚀 ソフトウェアエンジニア向け

一般的なワークフロー

1. コードのバックアップと共有

# プロジェクトファイルのアップロード
@mcp Upload my entire src/ directory to S3
@mcp Generate a 7 - day URL for team - config.json

2. CI/CDの統合

# デプロイメントスクリプト内で
mcp-s3 --root ./build upload dist.tar.gz

3. ログ管理

# アプリケーションログのアップロード
@mcp Upload today's error.log to S3
@mcp List all log files from this month

4. アセット管理

# プロジェクトアセットの管理
@mcp Upload design - assets.zip
@mcp Download latest - assets.zip to ./assets/

開発環境のセットアップ

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時間）。
• 競合検出：誤ったファイルの上書きを防止します。

📦 インストールオプション

# インストールせずに実行（推奨）
uvx mcp-s3

# グローバルにインストール
pip install mcp-s3

# 開発用インストール
git clone && uv sync

🚨 トラブルシューティング

"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

📚 リンク

• PyPI：https://pypi.org/project/mcp-s3/
• GitHub：https://github.com/dayongd1/mcp-s3
• MCP Docs：https://modelcontextprotocol.io/
• AWS S3 Setup：AWS_SETUP_GUIDE.md を参照してください。

Built with FastMCP | Python 3.10+ | MIT License