S3 MCP Server

S3 MCP サーバー

Amazon S3 バケットにアクセスするための Model Context Protocol（MCP）サーバーです。このサーバーは MCP を介して S3 ストレージとシームレスに連携し、ストリーミング機能を利用して PDF を含む大容量ファイルを効率的に扱えます。

機能

• プレフィックスによるフィルタリングに対応した S3 バケット内オブジェクトの一覧表示
• ストリーミングによる大容量ファイルの効率的な処理
• AWS 認証情報の安全な管理
• TypeScript サポート
• カスタマイズ可能なオプションを備えた CLI インターフェース

インストール

npx -y @geunoh/s3-mcp-server

使用方法

コマンドラインオプション

npx -y @geunoh/s3-mcp-server [options]

オプション：

• --port, -p：サーバーのポート（デフォルト：3000）
• --region, -r：AWS リージョン（デフォルト：ap-northeast-2）
• --bucket, -b：S3 バケット名（デフォルト：my-dancing-bucket）
• --content-type, -t：アップロード／ダウンロードする入力ファイルのコンテンツタイプ（デフォルト：application/octet-stream）

環境変数

必須：

export AWS_ACCESS_KEY_ID="your_access_key"
export AWS_SECRET_ACCESS_KEY="your_secret_key"

任意：

export AWS_REGION="ap-northeast-2"
export S3_BUCKET_NAME="my-bucket-name"
export CONTENT_TYPE="application/octet-stream" # Optional: default MIME type for uploads/downloads

MCP 連携

mcp.json に追加します：

{
  "mcpServers": {
    "s3-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@geunoh/s3-mcp-server",
        "--region",
        "us-east-1",
        "--bucket",
        "my-test-bucket",
        "--content-type",
        "text/plain"
      ],
      "env": {
        "AWS_ACCESS_KEY_ID": "YOUR_AWS_ACCESS_KEY_ID",
        "AWS_SECRET_ACCESS_KEY": "YOUR_AWS_SECRET_ACCESS_KEY"
      }
    }
  }
}

または、次のようにします：

{
  "mcpServers": {
    "s3-mcp-server": {
      "command": "npx",
      "args": ["-y", "@geunoh/s3-mcp-server"],
      "env": {
        "AWS_ACCESS_KEY_ID": "YOUR_AWS_ACCESS_KEY_ID",
        "AWS_SECRET_ACCESS_KEY": "YOUR_AWS_SECRET_ACCESS_KEY",

        // optional
        "AWS_REGION": "us-east-1",
        "S3_BUCKET_NAME": "my-test-bucket"
      }
    }
  }
}

利用可能な MCP 関数

listObjects

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

パラメーター：

• prefix（任意）：プレフィックスでオブジェクトを絞り込みます

getObject

S3 バケットからオブジェクトを取得します。ストリーミングにより、大容量ファイル向けに最適化されています。

パラメーター：

• key：取得するオブジェクトのキー

戻り値：

• stream：オブジェクトの内容を表す ReadableStream
• contentType：オブジェクトの MIME タイプ
• contentLength：オブジェクトのサイズ（バイト単位）
• lastModified：最終更新日時
• text：生の PDF ByteArray のテキストバッファー

AWS IAM 権限

最低限必要な権限（s3-policy.json を参照）：

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["s3:ListBucket", "s3:GetObject"],
      "Resource": "arn:aws:s3:::my-bucket-name"
    }
  ]
}

開発

1. リポジトリをクローンします：

git clone https://github.com/Geun-Oh/s3-mcp-server.git
cd s3-mcp-server

2. 依存関係をインストールします：

npm install

3. プロジェクトをビルドします：

npm run build

4. ローカルで実行します：

node dist/cli.js

プロジェクト構成

.
├── src/              # TypeScript source files
├── dist/            # Compiled JavaScript files and runtime dependencies
├── tsconfig.json    # TypeScript configuration
└── package.json     # Project configuration and dependencies

デプロイ

1. 新しいバージョンタグを作成します：

npm version patch

2. npm レジストリにプッシュします：

npm publish --access public

新しいバージョンタグがプッシュされると、GitHub Actions のワークフローによってパッケージが自動的に公開されます。

ライセンス

MIT

コントリビューション

Issue とプルリクエストを歓迎します。変更によって既存のコードスタイルが維持され、適切なテストが含まれていることを確認してください。