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