s3

S3 MCP サーバー

きめ細かなツールアクセス制御を備えた、AWS S3 操作向けの MCP サーバーです。S3 バケットおよびオブジェクトの読み取り／書き込み操作に対応し、セキュリティと権限を管理するために、設定可能なツールグループを提供します。

主な特長

• S3 バケットとオブジェクトの包括的な管理（一覧表示、取得、アップロード、コピー、削除）
• ツールグループ（readonly、readwrite）によるきめ細かなアクセス制御
• 環境変数による個別ツールの有効化／無効化
• ヘルスチェックによる AWS 認証情報の検証
• S3 互換エンドポイントに対応（MinIO、LocalStack など）
• 厳密な型チェックを備えた TypeScript
• 包括的なテスト（機能テスト、統合テスト、手動テスト）

機能

ツール

ツール	グループ	説明
list_buckets	readonly	AWS アカウント内のすべての S3 バケットを一覧表示します
list_objects	readonly	プレフィックスとページネーションを指定して、バケット内のオブジェクトを一覧表示します
get_object	readonly	オブジェクトの内容をテキストとして取得します
head_bucket	readonly	バケットが存在し、アクセス可能かを確認します
put_object	readwrite	オブジェクトをアップロードまたは更新します
delete_object	readwrite	バケットからオブジェクトを削除します
copy_object	readwrite	同じバケット内、または別のバケットにオブジェクトをコピーします
create_bucket	readwrite	新しい S3 バケットを作成します
delete_bucket	readwrite	空の S3 バケットを削除します

リソース

リソース	説明
s3://config	サーバーの設定とステータス（デバッグ用）

ツールグループ

S3_ENABLED_TOOLGROUPS 環境変数を使用して、利用可能なツールを制御します。

グループ	説明
readonly	読み取り専用の操作（一覧表示、取得、確認）
readwrite	書き込み操作（アップロード、削除、コピー、作成）

例：

• S3_ENABLED_TOOLGROUPS="readonly" - 読み取り操作のみ
• S3_ENABLED_TOOLGROUPS="readonly,readwrite" - すべての操作
• 未設定 - すべてのツールが有効（デフォルト）

個別ツールの制御

特定のツールをきめ細かく制御します。

• S3_ENABLED_TOOLS="list_buckets,get_object" - これらのツールのみを有効化します
• S3_DISABLED_TOOLS="delete_bucket,delete_object" - これらのツールを無効化します

単一バケットモード

S3_BUCKET を使用して、すべての操作を特定のバケットに限定します。

S3_BUCKET="my-bucket"

設定すると：

• すべてのオブジェクト操作が自動的にこのバケットに限定されます
• バケットレベルのツール（list_buckets、create_bucket、delete_bucket、head_bucket）は非表示になります
• bucket パラメーターが自動的に挿入され、ツールの入力から非表示になります
• copy_object では、コピー元とコピー先の両方が指定したバケットに限定されます

より広範な S3 権限を付与することなく、アクセスを単一のバケットに制限する場合に便利です。

クイックスタート

設定

環境変数

変数	必須	説明	デフォルト
AWS_ACCESS_KEY_ID	はい	AWS アクセスキー ID	-
AWS_SECRET_ACCESS_KEY	はい	AWS シークレットアクセスキー	-
AWS_REGION	いいえ	S3 操作用の AWS リージョン	us-east-1
AWS_ENDPOINT_URL	いいえ	カスタム S3 エンドポイント（MinIO など）	-
S3_FORCE_PATH_STYLE	いいえ	パス形式のアドレス指定を使用（MinIO 用）	false
S3_BUCKET	いいえ	操作対象を単一のバケットに制限	-
S3_ENABLED_TOOLGROUPS	いいえ	カンマ区切りのツールグループ	すべて有効
S3_ENABLED_TOOLS	いいえ	有効にする特定のツール	-
S3_DISABLED_TOOLS	いいえ	無効にする特定のツール	-
SKIP_HEALTH_CHECKS	いいえ	認証情報の検証をスキップ	false

Claude Desktop の設定

MCP サーバーを初めて使用する場合は、Claude Desktop アプリケーションを用意し、公式の MCP セットアップ手順に従ってください。

macOS：~/Library/Application Support/Claude/claude_desktop_config.json

Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "s3": {
      "command": "npx",
      "args": ["-y", "s3-aws-mcp-server"],
      "env": {
        "AWS_ACCESS_KEY_ID": "your-access-key-id",
        "AWS_SECRET_ACCESS_KEY": "your-secret-access-key",
        "AWS_REGION": "us-east-1",
        "S3_ENABLED_TOOLGROUPS": "readonly"
      }
    }
  }
}

Claude Desktop を再起動すれば、準備完了です。

読み取り専用モード

より安全に調べるには、読み取り操作のみを有効にしてください。

{
  "env": {
    "S3_ENABLED_TOOLGROUPS": "readonly"
  }
}

S3 互換サービスでの使用

MinIO、LocalStack、その他の S3 互換サービスの場合：

{
  "env": {
    "AWS_ACCESS_KEY_ID": "minioadmin",
    "AWS_SECRET_ACCESS_KEY": "minioadmin",
    "AWS_REGION": "us-east-1",
    "AWS_ENDPOINT_URL": "http://localhost:9000",
    "S3_FORCE_PATH_STYLE": "true"
  }
}

注： S3_FORCE_PATH_STYLE は、仮想ホスト形式（bucket-name.localhost:9000）ではなく、パス形式（localhost:9000/bucket-name）のアドレス指定を使用する MinIO や一部の S3 互換サービスで必要です。

開発

依存関係のインストール

npm run install-all

ビルド

npm run build

開発モードでの実行

npm run dev

テスト

# Run functional tests
npm run test:run

# Run integration tests (full MCP protocol)
npm run test:integration

# Run manual tests (real AWS - requires .env)
npm run test:manual:setup  # First time only
npm run test:manual

# Run all automated tests
npm run test:all

手動テストのセットアップ

s3 ディレクトリに .env ファイルを作成します。

AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
AWS_REGION=us-east-1

次に、以下を実行します。

npm run test:manual

プロジェクト構成

s3/
├── local/                 # Local server implementation
│   ├── src/
│   │   ├── index.ts      # Main entry point with env validation
│   │   └── index.integration-with-mock.ts
│   └── package.json
├── shared/               # Shared business logic
│   ├── src/
│   │   ├── server.ts     # Server factory with DI
│   │   ├── tools.ts      # Tool registration with grouping
│   │   ├── tools/        # Individual tool implementations
│   │   ├── resources.ts  # Resource implementations
│   │   ├── s3-client/    # AWS S3 client wrapper
│   │   └── logging.ts
│   └── package.json
├── tests/                # Test suite
│   ├── functional/       # Unit tests with mocks
│   ├── integration/      # MCP protocol tests
│   ├── manual/          # Real API tests
│   └── mocks/           # Mock implementations
└── package.json         # Root workspace config

ライセンス

MIT