MCP S3 Uploader

🚀 mcp-s3-uploader

MCP (Model Context Protocol) 標準入出力サーバーで、ローカル画像またはクリップボード画像（macOS）をAmazon S3にアップロードし、署名付きGET URLを返します。

下流のツール（例：v0 MCP）が**imageUrl**を必要とするが、あなたが持っているのが以下の場合に最適です。

• ローカルファイルパス (./design.png)
• クリップボードにコピーされたスクリーンショット（ファイルパスなし）

✨ 提供される機能

• ✅ upload_image — ファイルパスでローカル画像をアップロード → 署名付きURLを返す
• ✅ upload_clipboard_image (macOS) — 現在のクリップボード画像をアップロード → 署名付きURLを返す
  • 利用可能な場合はpngpasteを使用（推奨）
  • pbpaste -Prefer pngにフォールバック（追加のインストール不要だが、信頼性が低い）
• ✅ Codex CLI + MCP パイプライン向けに構築
• ✅ プライベートS3バケットをサポート（バケットを公開する必要はない）

🔁 典型的なフロー

(ローカルパスまたはクリップボード画像)
        │
        ▼
mcp-s3-uploader (MCPサーバー)
        │
        ▼
S3 PutObject (プライベート)
        │
        ▼
署名付きGET URL (期限付き)
        │
        ▼
v0などのツールにimageUrlとしてURLを渡す

📦 インストール

必要条件

• Node.js >= 18
• AWS SDKがアクセスできるAWS資格情報（推奨: AWS_PROFILE）
• S3バケット（プライベート推奨）

オプション（macOSでのクリップボードの信頼性向上のため推奨）

brew install pngpaste

インストールしない場合、サーバーはpbpaste -Prefer pngをフォールバックとして試みます。

🚀 クイックスタート (5分)

1) 依存関係のインストール

npm install

2) .env ファイルの作成

プロジェクトのルートに.envファイルを作成します。

S3_BUCKET=your-bucket-name
AWS_REGION=ap-northeast-2
S3_PREFIX=codex-v0/
URL_EXPIRES_IN=86400
AWS_PROFILE=signin

環境変数の説明

• S3_BUCKET (必須): あなたのS3バケット名
• AWS_REGION (オプション): デフォルト ap-northeast-2
• S3_PREFIX (オプション): デフォルト codex-v0/
• URL_EXPIRES_IN (オプション): URLの有効期限（秒）（デフォルト 86400 = 24時間）
• AWS_PROFILE (オプション): AWS CLIのプロファイル名

3) ビルド

npm run build

4) MCPインスペクターでテスト（推奨）

npx @modelcontextprotocol/inspector node ./build/index.js

ターミナルに表示されるインスペクターのURLを開き、以下を試してみます。

ツール: upload_image

{ "path": "/absolute/path/to/design.png" }

ツール: upload_clipboard_image

{}

🧩 Codex CLI (MCP) との連携

MCPサーバーの登録

プロジェクトのルートから以下を実行します。

ABS_PATH="$(pwd)/build/index.js"

codex mcp add s3Uploader   --env S3_BUCKET=your-bucket-name   --env AWS_REGION=ap-northeast-2   --env S3_PREFIX=codex-v0/   --env URL_EXPIRES_IN=86400   --env AWS_PROFILE=signin   -- node "$ABS_PATH"

確認:

codex mcp list

Codexでの使用

ローカルファイル

upload_imageを使用して/path/to/design.pngをアップロードし、URLのみを返す。

クリップボード

upload_clipboard_imageを使用してクリップボードの画像をアップロードし、URLのみを返す。

🔥 エンドツーエンド: Codex + v0 MCP (推奨)

以下が用意できたら:

• s3Uploader MCPサーバー（このリポジトリ）
• v0 MCPサーバー

以下を自動的に行うスキルを作成できます。

1. ローカル/クリップボード画像をアップロード → 2) imageUrlでv0を呼び出す

スキルフォルダの作成

mkdir -p ~/.codex/skills/v0-s3-image-bridge

ファイルを作成: ~/.codex/skills/v0-s3-image-bridge/SKILL.md

---
name: v0-s3-image-bridge
description: ユーザーが画像（ローカルパスまたはクリップボード）でv0を使用するように要求した場合、MCP（upload_image / upload_clipboard_image）を介して画像をS3にアップロードし、返されたURLを使用してv0_generate_from_imageを呼び出します。
---

## ワークフロー
1) ユーザーがローカル画像パスを提供した場合 -> upload_image({ path }) を呼び出す
2) それ以外の場合 -> upload_clipboard_image({}) を呼び出す
3) 返されたURLを抽出する
4) v0_generate_from_image({ imageUrl: URL, prompt: user_instructions }) を呼び出す
5) v0の出力を返す

その後、Codexで以下のように入力します。

v0로 지금 클립보드 이미지 기반 UI 만들어줘. shadcn/ui + tailwind, 반응형.

🔧 ツールAPI

upload_image

ローカル画像ファイルパスをS3にアップロードし、署名付きGET URLを返します。

入力

• path (文字列, 必須)
• keyPrefix (文字列, オプション)
• expiresInSeconds (数値, オプション)

出力

• 1行目: URL
• 2行目: JSONメタデータ

upload_clipboard_image (macOS)

現在のクリップボード画像をS3にアップロードし、署名付きGET URLを返します。

入力

• keyPrefix (文字列, オプション)
• expiresInSeconds (数値, オプション)

クリップボードに関する注意事項

• インストールされている場合はpngpasteを使用（推奨）
• pbpaste -Prefer pngにフォールバック

🔐 推奨IAMポリシー（最小限）

プレフィックスに制限する:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowPutGetInPrefixOnly",
      "Effect": "Allow",
      "Action": ["s3:PutObject", "s3:GetObject"],
      "Resource": "arn:aws:s3:::YOUR_BUCKET/codex-v0/*"
    }
  ]
}

✅ バケットを公開する必要はありません。

🧹 オプション: S3ライフサイクルのクリーンアップ

これを日常的に使用する場合、オブジェクトが蓄積されます。N日後にプレフィックス以下のオブジェクトを削除するS3ライフサイクルルールを検討してください。

例（概念）:

• プレフィックス: codex-v0/
• 有効期限: 30日

トラブルシューティング

Missing env: S3_BUCKET

• .env が存在し、読み込まれていることを確認する、または
• codex mcp add --env ... を介して環境変数を渡す

クリップボードのアップロードが失敗する

• クリップボードに画像が含まれていることを確認する（まずスクリーンショットを撮る）
• 信頼性を高めるためにpngpasteをインストールする:

  brew install pngpaste
  

S3 AccessDenied

• IAMがs3:PutObject（および署名付きURLの使用にはs3:GetObject）を許可していることを確認する
• バケット名/リージョンを再確認する

署名付きURLが期限切れになった

• URL_EXPIRES_IN を増やす（例: 48時間の場合は 172800）

セキュリティに関する注意事項

• AWS資格情報をコミットしないでください。
• AWS_PROFILE またはSSOベースのワークフローを使用することを推奨します。
• バケットをプライベートに保ち、署名付きURLを使用します。

📄 ライセンス

MIT