MCP S3 Uploader

🚀 MCP S3 上傳器

MCP（模型上下文協議）標準輸入輸出服務器，可將本地圖像或剪貼板圖像（僅限 macOS）上傳到亞馬遜 S3，並返回一個預簽名的 GET URL。

此工具非常適合下游工具（如 v0 MCP）需要 imageUrl，但你只有以下情況的工作流程：

• 本地文件路徑（./design.png）
• 複製到剪貼板的截圖（無文件路徑）

🚀 快速開始

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

{}

✨ 主要特性

• ✅ upload_image — 通過文件路徑上傳本地圖像 → 返回預簽名 URL
• ✅ upload_clipboard_image（macOS） — 上傳當前剪貼板圖像 → 返回預簽名 URL
  • 若可用，使用 pngpaste（推薦）
  • 回退到 pbpaste -Prefer png（無需額外安裝，但可靠性較低）
• ✅ 專為 Codex CLI + MCP 管道構建
• ✅ 支持私有 S3 存儲桶（無需將存儲桶公開）

🔁 典型流程

(本地路徑或剪貼板圖像)
        │
        ▼
mcp-s3-uploader (MCP 服務器)
        │
        ▼
S3 PutObject (私有)
        │
        ▼
預簽名 GET URL (有有效期)
        │
        ▼
將 URL 作為 imageUrl 傳遞給 v0 等工具

📦 安裝指南

必備條件

• Node.js >= 18
• AWS SDK 可訪問的 AWS 憑證（推薦：AWS_PROFILE）
• 一個 S3 存儲桶（推薦使用私有存儲桶）

可選步驟（推薦用於提高 macOS 上剪貼板的可靠性）

brew install pngpaste

如果你不安裝它，服務器將嘗試使用 pbpaste -Prefer png 作為回退方案。

🧩 與 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（數字，可選）

輸出

• 第一行：URL
• 第二行：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 生命週期清理

如果你每天使用此工具，對象會不斷累積。考慮設置一個 S3 生命週期規則，在 N 天后刪除前綴下的對象。

示例（概念）：

• 前綴：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（例如，設置為 172800 以延長到 48 小時）

安全注意事項

• 不要提交 AWS 憑證。
• 優先使用 AWS_PROFILE 或基於 SSO 的工作流程。
• 保持存儲桶私有；使用預簽名 URL。

📄 許可證

MIT