S3 MCP Server

S3 MCP サーバー

Amazon S3 用の Model Context Protocol (MCP) サーバーで、S3 バケットやオブジェクトを操作するためのツールを提供します。

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

機能

🚀 MCP トランスポート対応

• ✅ STDIO トランスポート - Claude Desktop 向けの直接プロセス通信
• ✅ HTTP トランスポート - Web クライアント向けの Server-Sent Events を備えた REST API
• ✅ Streamable HTTP - 応答性の高いインタラクションのためのリアルタイムストリーミング

🛠️ 利用可能なツール

• ✅ list-buckets - アクセス可能な S3 バケットをフィルタリング付きで一覧表示
• ✅ list-objects - バケット内のオブジェクトをプレフィックスフィルタリング付きで閲覧
• ✅ get-object - オブジェクトの内容を取得（テキスト/バイナリ対応）

🐳 デプロイオプション

• ✅ ローカル Node.js - npm/node による直接実行
• ✅ Docker CLI - カスタム設定によるコンテナデプロイ
• ✅ Docker Compose - ローカルテスト用の MinIO を含むフルスタック
• ✅ MCP Inspector - 組み込みのデバッグおよびテストインターフェース

概要

この MCP サーバーは、Claude のような LLM が AWS S3 ストレージと連携できるようにします。以下のためのツールを提供します：

• 利用可能な S3 バケットの一覧表示
• バケット内のオブジェクトの一覧表示
• オブジェクトの内容の取得

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

インストール

前提条件

• Node.js 18 以上
• npm または yarn
• AWS 認証情報の設定（環境変数または AWS 認証情報ファイルのいずれかを使用）
• Docker（任意、コンテナ環境でのセットアップ用）

セットアップ

1. npm でインストールします：

# Install globally via npm
npm install -g aws-s3-mcp

# Or as a dependency in your project
npm install aws-s3-mcp

2. ソースからビルドする場合：

# 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

3. 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 による直接実行

サーバーはデフォルトで HTTP トランスポートで動作するため、テストとデバッグが簡単です：

# Using npx (HTTP transport by default)
npx aws-s3-mcp

# If installed globally (HTTP transport)
npm install -g aws-s3-mcp
aws-s3-mcp

# If running from cloned repository (HTTP transport)
npm start

# Or directly (HTTP transport)
node dist/index.js

# Explicit HTTP transport
node dist/index.js --http

# STDIO transport (for Claude Desktop integration)
node dist/index.js --stdio

HTTP トランスポート（デフォルト）で実行すると、サーバーはポート 3000 で起動し、以下を提供します：

• ヘルスチェックエンドポイント：http://localhost:3000/health
• MCP エンドポイント：http://localhost:3000/mcp
• SSE エンドポイント：http://localhost:3000/sse

Docker セットアップ 🐳

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

Docker CLI を使用する場合

1. Docker イメージをビルドします:

docker build -t aws-s3-mcp .

2. 環境変数を指定してコンテナを実行します:

# 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

3. コンテナのログを確認します:

docker logs aws-s3-mcp-server

4. コンテナを停止して削除します:

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

注: HTTP トランスポート(デフォルト)の場合は、-p 3000:3000 を追加して HTTP ポートを公開してください。STDIO トランスポート(Claude Desktop)の場合は、Docker exec を使用して直接通信するため、ポートマッピングは不要です。

Docker Compose を使用する場合

1. Docker コンテナをビルドして起動します:

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

# View logs
docker compose logs -f s3-mcp

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

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 によるデバッグ 🔍

run-inspector.sh スクリプトは、MCP Inspector を使用して S3 MCP サーバーを簡単にテストおよびデバッグする方法を提供します。複数のトランスポートタイプとデプロイモードをサポートしています。

クイックスタート

# Show all available options
./run-inspector.sh --help

# Run locally with HTTP transport (default)
./run-inspector.sh

# Run with Docker Compose and MinIO for testing
./run-inspector.sh --docker-compose

トランスポートタイプ

サーバーは 2 つのトランスポートプロトコルをサポートしています:

HTTP トランスポート

• 最適な用途: Web ベースのデバッグ、外部クライアント接続
• 提供機能: REST API エンドポイント、Server-Sent Events (SSE)
• ポート: 3000 (HTTP)、3001+ (Inspector UI)

STDIO トランスポート

• 最適な用途: 直接的なプロセス通信、Claude Desktop との統合
• 提供機能: 標準入力/出力による通信
• ポート: なし(直接的なプロセス通信)

使用例

1. ローカル開発 (HTTP)

# Default: HTTP transport for local debugging
./run-inspector.sh

# Explicit HTTP transport
./run-inspector.sh --http

これにより、以下が実行されます:

• 必要に応じてプロジェクトをビルド
• ポート 3000 で HTTP トランスポートを使用して MCP サーバーを起動
• ブラウザで MCP Inspector を起動
• 以下のエンドポイントを提供:
  • ヘルスチェック: http://localhost:3000/health
  • MCP エンドポイント: http://localhost:3000/mcp
  • SSE エンドポイント: http://localhost:3000/sse

2. ローカル開発 (STDIO)

# STDIO transport for local debugging
./run-inspector.sh --stdio

このモードでは、標準入力/出力を使用して MCP Inspector をサーバープロセスに直接接続します。

3. 実際の AWS を使用した Docker (STDIO)

# Create .env file with your AWS credentials
cp .env.example .env
# Edit .env with your AWS credentials

# Run with Docker using STDIO transport (default for Docker)
./run-inspector.sh --docker

これにより、以下が実行されます:

• 必要に応じて Docker イメージをビルド
• AWS 認証情報を使用してコンテナを起動
• Docker exec 経由で MCP Inspector を接続

4. 実際の AWS を使用した Docker (HTTP)

# Run with Docker using HTTP transport
./run-inspector.sh --docker --http

これにより、以下が実行されます:

• ポート 3000 でコンテナ化された HTTP サーバーを起動
• MCP Inspector を HTTP エンドポイントに接続
• HTTP ベースの統合のテストに便利です

5. MinIO を使用した Docker Compose (テスト)

# Run with MinIO for local testing (no AWS credentials needed)
./run-inspector.sh --docker-compose

これにより、以下が実行されます:

• MinIO S3 互換ストレージを起動
• テストバケットを作成: test-bucket-1、test-bucket-2
• テスト用のサンプルファイルをアップロード
• MinIO に接続された S3 MCP サーバーを起動
• MCP Inspector を起動
• http://localhost:9001 で MinIO Web UI を提供(ログイン: minioadmin/minioadmin)

詳細オプション

強制再ビルド

# Force Docker image rebuild
./run-inspector.sh --docker --force-rebuild
./run-inspector.sh --docker-compose --force-rebuild

デバッグのヒント

1. コンテナのログを確認する:

   # For Docker CLI mode
   docker logs aws-s3-mcp-server
   
   # For Docker Compose mode
   docker compose logs s3-mcp
   

2. エンドポイントを手動でテストする:

   # Health check
   curl http://localhost:3000/health
   
   # MinIO health (Docker Compose)
   curl http://localhost:9000/minio/health/live
   

3. MinIO Web UI にアクセスする(Docker Compose のみ):

   • URL: http://localhost:9001
   • ユーザー名: minioadmin
   • パスワード: minioadmin

クリーンアップ

# Stop and remove Docker containers
docker stop aws-s3-mcp-server && docker rm aws-s3-mcp-server

# Stop Docker Compose services
docker compose down

# Stop specific HTTP server container
docker stop aws-s3-mcp-http-server && docker rm aws-s3-mcp-http-server

トラブルシューティング

• ポートの競合: ポート 3000 が使用中の場合は、他のサービスを停止するか、ポートを変更してください
• AWS 認証情報: Docker モードでは、.env ファイルに有効な AWS 認証情報があることを確認してください
• ビルドエラー: --force-rebuild を使用して Docker イメージを再ビルドしてください
• 接続の問題: docker ps でコンテナが実行中であることを確認してください

クイックリファレンス

コマンド	トランスポート	環境	説明
./run-inspector.sh	HTTP	ローカル	HTTP トランスポートによるローカル開発
./run-inspector.sh --stdio	STDIO	ローカル	STDIO トランスポートによるローカル開発
./run-inspector.sh --docker	STDIO	Docker + AWS	AWS 認証情報を使用した Docker コンテナ
./run-inspector.sh --docker --http	HTTP	Docker + AWS	HTTP トランスポートを使用した Docker コンテナ
./run-inspector.sh --docker-compose	STDIO	Docker + MinIO	MinIO を使用したローカルテスト（AWS 不要）

Claude Desktop への接続

このサーバーを Claude Desktop で使用するには、プロセス間の直接通信のために STDIO トランスポート（デフォルトの HTTP トランスポートではなく）を使用する必要があります。

1. Claude Desktop の設定ファイルを編集します。

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. 設定に S3 MCP サーバーを追加します。

{
  "mcpServers": {
    "s3": {
      "command": "npx",
      "args": ["aws-s3-mcp", "--stdio"],
      "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 Desktop 向けの Docker オプション 🐳

Claude Desktop が実行中の Docker コンテナを MCP サーバーとして使用するように設定することもできます。

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

⚠️ 重要な前提条件: この Docker 設定を機能させるには、Claude Desktop を起動する 前に、必ず Docker コンテナをビルドして実行する必要があります。

# 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", "--stdio"],
      "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"
      }
    }
  }
}

利用可能なツール

list-buckets

サーバーがアクセス権限を持つ利用可能な 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"
  }
]

list-objects

指定した 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"
  }
]

get-object

指定した 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 での使用

デスクトップアプリで Claude とやり取りする際、次のような S3 操作を実行するように依頼できます。

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

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

ライセンス

MIT