S3 MCP サーバー

Name: S3 MCP Server
Author: samuraikun

トリヴィスキャン npmバージョン npmダウンロードライセンス: MIT Node.js バージョン

S3 バケットおよびオブジェクトと対話するためのツールを提供する Amazon S3 モデルコンテキストプロトコル (MCP) サーバー。

https://github.com/user-attachments/assets/d05ff0f1-e2bf-43b9-8d0c-82605abfb666

概要

このMCPサーバーは、Claudeのような大規模言語モデル（LLM）がAWS S3ストレージと連携できるようにします。以下のツールを提供します。

利用可能なS3バケットの一覧表示
バケット内のオブジェクトの一覧表示
オブジェクトの内容を取得しています

サーバーは TypeScript と MCP SDK を使用して構築されており、LLM が S3 とインターフェースするための安全で標準化された方法を提供します。

Related MCP server: AWS MCP Server

インストール

前提条件

Node.js 18以上
npmまたはyarn
AWS 認証情報が設定されている（環境変数または AWS 認証情報ファイル経由）
Docker（オプション、コンテナ化されたセットアップ用）

設定

npm 経由でインストール:

# Install globally via npm npm install -g aws-s3-mcp # Or as a dependency in your project npm install aws-s3-mcp

ソースからビルドする場合:

# Clone the repository git clone https://github.com/samuraikun/aws-s3-mcp.git cd aws-s3-mcp # Install dependencies and build npm install npm run build

AWS 認証情報と S3 アクセスを構成します。

AWS 設定で.envファイルを作成します。

AWS_REGION=us-east-1 S3_BUCKETS=bucket1,bucket2,bucket3 S3_MAX_BUCKETS=5 AWS_ACCESS_KEY_ID=your-access-key AWS_SECRET_ACCESS_KEY=your-secret-key

または、これらを環境変数として設定します。

構成

サーバーは次の環境変数を使用して構成できます。

変数	説明	デフォルト
`AWS_REGION`	S3バケットが配置されているAWSリージョン	`us-east-1`
`S3_BUCKETS`	許可された S3 バケット名のカンマ区切りリスト	（空の）
`S3_MAX_BUCKETS`	リストに返されるバケットの最大数	`5`
`AWS_ACCESS_KEY_ID`	AWS アクセスキー（デフォルトの認証情報を使用していないとき）	(AWS 設定から)
`AWS_SECRET_ACCESS_KEY`	AWS 秘密キー（デフォルトの認証情報を使用していないとき）	(AWS 設定から)

サーバーの実行

直接Node.js実行

Node.js を使用してサーバーを直接実行できます。

# Using npx (without installing) npx aws-s3-mcp # If installed globally npm install -g aws-s3-mcp aws-s3-mcp # If running from cloned repository npm start # Or directly node dist/index.js

Docker のセットアップ 🐳

Docker CLI または Docker Compose を使用して、S3 MCP サーバーを Docker コンテナとして実行できます。

Docker CLIの使用

Docker イメージをビルドします。

docker build -t aws-s3-mcp .

環境変数を使用してコンテナを実行します。

# Option 1: Pass environment variables directly docker run -d \ -e AWS_REGION=us-east-1 \ -e S3_BUCKETS=bucket1,bucket2 \ -e S3_MAX_BUCKETS=5 \ -e AWS_ACCESS_KEY_ID=your-access-key \ -e AWS_SECRET_ACCESS_KEY=your-secret-key \ --name aws-s3-mcp-server \ aws-s3-mcp # Option 2: Use environment variables from .env file docker run -d \ --env-file .env \ --name aws-s3-mcp-server \ aws-s3-mcp

コンテナのログを確認します。

docker logs aws-s3-mcp-server

コンテナを停止して削除します。

docker stop aws-s3-mcp-server docker rm aws-s3-mcp-server

コンテナーは、直接の HTTP 接続ではなく、Docker exec を介して Claude Desktop で使用されるように設計されているため、ポートを公開しないことに注意してください。

Docker Composeの使用

Docker コンテナをビルドして起動します。

# Build and start the container docker compose up -d s3-mcp # View logs docker compose logs -f s3-mcp

コンテナを停止するには:

docker compose down

MinIO で Docker を使ってテストする

Docker Compose セットアップには、ローカルテスト用の MinIO サービスが含まれています。

# Start MinIO and the MCP server docker compose up -d # Access MinIO console at http://localhost:9001 # Default credentials: minioadmin/minioadmin

MinIO サービスは、2 つのテストバケット ( test-bucket-1とtest-bucket-2 ) を自動的に作成し、テスト用のサンプルファイルをアップロードします。

MCP Inspectorでのデバッグ

MCP Inspector を使用してサーバーをデバッグするには:

# Run inspector with local Node.js sh run-inspector.sh # Run inspector with Docker Compose and MinIO sh run-inspector.sh --docker-compose # Run inspector with Docker CLI (without Docker Compose) sh run-inspector.sh --docker

--docker-composeオプションを使用すると、スクリプトは次の処理を実行します。

MinIOとS3 MCPサーバーコンテナが実行されていない場合は起動します。
S3 MCPサーバーに接続されたMCPインスペクターを起動します。
その後、S3ツールをローカルのMinIOインスタンスに対してテストすることができます。

Claudeデスクトップに接続しています

このサーバーをClaude Desktopで使用するには:

Claude Desktop 構成ファイルを編集します。
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
S3 MCP サーバーを構成に追加します。

{ "mcpServers": { "s3": { "command": "npx", "args": ["aws-s3-mcp"], "env": { "AWS_REGION": "us-east-1", "S3_BUCKETS": "bucket1,bucket2,bucket3", "S3_MAX_BUCKETS": "5", "AWS_ACCESS_KEY_ID": "your-access-key", "AWS_SECRET_ACCESS_KEY": "your-secret-key" } } } }

Claude デスクトップ用の Docker オプション 🐳

また、MCP サーバーで実行中の Docker コンテナを使用するように Claude Desktop を構成することもできます。

{ "mcpServers": { "s3": { "command": "docker", "args": ["exec", "-i", "aws-s3-mcp-server", "node", "dist/index.js"], "env": {} } } }

⚠️ 重要な前提条件: この Docker 構成が機能するには、Claude Desktop を起動する前に、。
# 1. First, build the Docker image (only needed once or after changes) docker build -t aws-s3-mcp . # 2. Then start the container (required each time before using with Claude) # Using Docker Compose (recommended) docker compose up -d s3-mcp # Or using Docker CLI docker run -d --name aws-s3-mcp-server --env-file .env aws-s3-mcp
実行中のコンテナがない場合、Claude Desktop は S3 ツールを使用しようとするとエラーを表示します。
上記のDocker設定では、 execを使用してMCPリクエストを実行中のコンテナに直接送信しています。Claudeはネットワークポートを経由せずコンテナと直接通信するため、ポートマッピングは必要ありません。

注意: 設定内のコンテナ名 ( aws-s3-mcp-server ) が実行中のコンテナの名前と一致していることを確認してください。

重要: 上記の設定を使用する場合は、次の点に注意してください。
AWS_ACCESS_KEY_IDとAWS_SECRET_ACCESS_KEY実際の認証情報に置き換えます。
S3_BUCKETSは、アクセスを許可するバケットのカンマ区切りのリストを含める必要があります。
AWS_REGIONバケットが配置されているリージョンに設定する必要があります

💣 Claude Desktopでエラーが発生した場合

Claude Desktop で上記の構成でエラーが発生した場合は、次のように絶対パスを使用してみてください。

# Get the path of node and aws-s3-mcp which node which aws-s3-mcp

{ "globalShortcut": "", "mcpServers": { "s3": { "command": "your-absolute-path-to-node", "args": ["your-absolute-path-to-aws-s3-mcp/dist/index.js"], "env": { "AWS_REGION": "your-aws-region", "S3_BUCKETS": "your-s3-buckets", "S3_MAX_BUCKETS": "your-max-buckets", "AWS_ACCESS_KEY_ID": "your-access-key", "AWS_SECRET_ACCESS_KEY": "your-secret-key" } } } }

利用可能なツール

リストバケット

サーバーがアクセス権限を持つ利用可能なS3バケットを一覧表示します。このツールは、表示されるバケットを制限するS3_BUCKETS設定に従います。

**パラメータ:**なし

出力例:

[ { "Name": "my-images-bucket", "CreationDate": "2022-03-15T10:30:00.000Z" }, { "Name": "my-documents-bucket", "CreationDate": "2023-05-20T14:45:00.000Z" } ]

リストオブジェクト

指定された S3 バケット内のオブジェクトを一覧表示します。

パラメータ:

bucket （必須）: オブジェクトを一覧表示するS3バケットの名前
prefix （オプション）：フィルターオブジェクトのプレフィックス（フォルダーパスなど）
maxKeys (オプション): 返されるオブジェクトの最大数

出力例:

[ { "Key": "sample.pdf", "LastModified": "2023-10-10T08:12:15.000Z", "Size": 2048576, "StorageClass": "STANDARD" }, { "Key": "sample.md", "LastModified": "2023-10-12T15:30:45.000Z", "Size": 1536000, "StorageClass": "STANDARD" } ]

オブジェクトを取得

指定されたS3バケットからオブジェクトを取得します。テキストファイルはプレーンテキストとして返され、バイナリファイルは限定された詳細情報とともに返されます。

パラメータ:

bucket （必須）: S3バケットの名前
key (必須): 取得するオブジェクトのキー（パス）

テキスト出力の例:

This is the content of a text file stored in S3. It could be JSON, TXT, CSV or other text-based formats.

バイナリ出力の例:

Binary content (image/jpeg): base64 data is /9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRof...

セキュリティに関する考慮事項

サーバーはS3_BUCKETS環境変数で指定されたバケットにのみアクセスします。
AWS認証情報にはバケットへの適切な権限が必要です
AWS の権限を設定するときは、最小権限の原則を使用します。
本番環境での使用には、特定のS3権限を持つIAMロールの使用を検討してください。

クロードとの使用

デスクトップアプリで Claude と対話する場合、次のような S3 操作を実行するように要求できます。

「すべてのS3バケットを一覧表示する」
「my-documents-bucket 内の PDF ファイルを要約する」
「my-documents-bucket から README.txt ファイルを取得する」

Claude は適切な MCP ツールを使用してリクエストを実行し、結果を表示します。

ライセンス

マサチューセッツ工科大学

S3 MCP Server