MCP S3 Uploader

mcp-s3上传器

一 MCP（模型上下文协议）stdio服务器 上传 本地图像 或 剪贴板图像（macOS） 到 亚马逊S3 并返回a 预签名GET URL.

这对于下游工具（例如。 v0 MCP)需要一个 imageUrl，但你只有：

• 本地文件路径(./design.png)
• 复制到剪贴板的屏幕截图（无文件路径）

______________________________________________________________________

✨ 你得到了什么

• ✅ upload_image --按文件路径上传本地图像→ 返回预签名的URL
• ✅ upload_clipboard_image （macOS） --上传当前剪贴板图像→ 返回预签名的URL

- 用途 pngpaste 如果可用（推荐） - 回落到 pbpaste -Prefer png （无需额外安装，但可靠性较低）

• ✅ 专为 Codex CLI+MCP 管道
• ✅ 支持私有S3存储桶（无需将存储桶公开）

______________________________________________________________________

🔁 典型流量

(Local path or Clipboard image)
        │
        ▼
mcp-s3-uploader (MCP server)
        │
        ▼
S3 PutObject (private)
        │
        ▼
Presigned GET URL (expires)
        │
        ▼
Pass URL to tools like v0 as imageUrl

______________________________________________________________________

需求

• 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

Env笔记

• S3_BUCKET （必填）：您的S3存储桶名称
• AWS_REGION （可选）：默认值 ap-northeast-2
• S3_PREFIX （可选）：默认值 codex-v0/
• URL_EXPIRES_IN （可选）：URL TTL（秒）（默认值 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中的使用

本地文件

上传 /path/to/design.png 使用 upload_image 并且仅返回URL。

剪贴板

使用上传我的剪贴板图像 upload_clipboard_image 并且仅返回URL。

______________________________________________________________________

🔥 端到端：Codex+v0 MCP（推荐）

一旦你有：

• s3Uploader MCP服务器（此仓库）
• v0 MCP服务器

您可以创建 技能 自动：

1. 上传本地/剪贴板图像→ 2) 调用v0 imageUrl

技能文件夹

创建：

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

创建文件： ~/.codex/skills/v0-s3-image-bridge/SKILL.md

---
name: v0-s3-image-bridge
description: When the user asks to use v0 with an image (local path or clipboard), upload the image to S3 via MCP (upload_image / upload_clipboard_image) and then call v0_generate_from_image using the returned URL.
---

## Workflow
1) If user provides a local image path -> call upload_image({ path })
2) Else -> call upload_clipboard_image({})
3) Extract returned URL
4) Call v0_generate_from_image({ imageUrl: URL, prompt: user_instructions })
5) Return v0 output

然后在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 存在并已加载，或
• 通过传递env codex mcp add --env ...

剪贴板上传失败

• 确保剪贴板包含图像（先截图）
• 安装 pngpaste 为了获得最佳可靠性：

  brew install pngpaste

第3页 AccessDenied

• 确保IAM允许 s3:PutObject （以及 s3:GetObject 用于预签名URL的使用）
• 仔细检查存储桶名称/区域

预设URL已过期

• 增加 URL_EXPIRES_IN （例如。 172800 48小时）

______________________________________________________________________

安全注意事项

• 做 不 提交AWS凭据。
• 更喜欢 AWS_PROFILE 或基于SSO的工作流。
• 保持桶的私密性；使用预签名的URL。

______________________________________________________________________

许可证

麻省理工学院