Upload Post

@upload-post/mcp

Upload-Post 的官方 Model Context Protocol（MCP） 服务。

任何兼容 MCP 的 AI Agent（ChatGPT、Claude Desktop、Claude Code、Cursor 等）都可以使用单个 API 密钥，在 TikTok、Instagram、YouTube、LinkedIn、Facebook、Pinterest、Threads、Reddit、Bluesky、X、Google Business、Discord、Telegram 等平台发布、安排、分析和管理社交媒体内容。

基于官方 upload-post SDK 和公开的 Upload-Post REST API 构建。

---

在 ChatGPT 中使用（无需设置）

Upload-Post 是经 OpenAI 审核的插件，列在 ChatGPT 的 Plugins（原名 Apps）中。在 ChatGPT 中打开 Upload-Post，或在 Plugins 中搜索 Upload-Post，点击 Install，然后点击 Connect，并使用 OAuth 登录。无需粘贴 MCP URL，你还可以使用 Upload Studio 小组件，直接从电脑发布视频文件、照片和轮播图。OpenAI dots 使用相同的插件：在 dot 的 Customize → Plugins 中选择该插件，并查看其权限。

想手动配置？在网页版 ChatGPT 中打开 Plugins，点击 +，选择 Add custom MCP server，将地址设为 https://mcp.upload-post.com/mcp，并将身份验证设为 OAuth。自定义 MCP 服务可在 Business、Enterprise 和 Edu 工作区执行写入操作。

在 Claude 中使用

在 claude.ai 或 Claude Desktop 中，打开 Customize → Connectors，点击 + Add，然后选择 Add custom connector，粘贴 https://mcp.upload-post.com/mcp，点击 Continue 并使用 OAuth 登录。所有 Claude 套餐均支持自定义连接器（免费套餐允许添加一个）。在 Claude Code 中：claude mcp add --transport http upload-post https://mcp.upload-post.com/mcp。

在 Perplexity Computer 中使用

在侧边栏中打开 Plugins（或 Customize → Connectors），然后选择 Add custom → Connector → Add MCP connector → Remote。使用 https://mcp.upload-post.com/mcp，并选择 Streamable HTTP 传输和 OAuth（或你的 Upload-Post API 密钥），点击 Add，然后点击 Upload-Post 卡片登录。

在 Gemini CLI 中使用

安装扩展，并在 Gemini 首次调用工具时使用 OAuth 登录：

gemini extensions install https://github.com/Upload-Post/upload-post-mcp

---

两种自行运行的方式

A) 本地 stdio（单用户）——最简单

服务在你的机器上运行，由 MCP 客户端启动。将以下内容添加到 ~/.claude/mcp.json（或 Cursor 设置等）中：

{
  "mcpServers": {
    "upload-post": {
      "command": "npx",
      "args": ["-y", "@upload-post/mcp"],
      "env": { "UPLOAD_POST_API_KEY": "YOUR_API_KEY" }
    }
  }
}

在 https://app.upload-post.com → API Keys 获取 API 密钥。重启客户端后，你应该会看到 58 个 upload-post 工具。

B) 托管 HTTP（多租户）——与多位用户共用一个服务

在任何支持 Docker 的主机（Fly、Railway、Cloud Run 或你自己的设备等）上运行服务，并让每位用户使用自己的 Upload-Post API 密钥连接。服务不会存储任何用户数据。

{
  "mcpServers": {
    "upload-post": {
      "url": "https://mcp.your-domain.com/mcp",
      "headers": {
        "Authorization": "ApiKey YOUR_OWN_UPLOAD_POST_API_KEY"
      }
    }
  }
}

对于仅允许使用 Bearer 的客户端，也可以使用 Authorization: Bearer <key>。

---

Agent 能做什么？

此服务提供 Upload-Post API 工具，以及一个 ChatGPT App UI 启动器。

分组	工具
上传	upload_video、upload_photos、upload_text、upload_document、open_upload_studio
媒体暂存	create_media_upload、complete_media_upload、get_media_upload、delete_media_upload
状态	get_status、get_job_status、get_history、get_media
排期	list_scheduled、cancel_scheduled、edit_scheduled
分析	get_analytics、get_total_impressions、get_post_analytics、get_cached_post_analytics、get_platform_metrics
受众	get_audience、get_suggestions
用户	get_account_info、list_users、get_connect_link、create_user、delete_user、generate_jwt、validate_jwt
页面/版块	get_facebook_pages、get_linkedin_pages、get_pinterest_boards、get_google_business_locations、get_google_business_reviews、reply_to_google_business_review、get_reddit_detailed_posts
帖子	retry_post、unpublish_post
评论	get_post_comments、create_comment、delete_comment、reply_to_comment、public_reply_to_comment、hide_comment、like_comment、pin_comment、edit_comment、hold_comment、approve_comment、ignore_comment、set_post_comments、comment_action
TikTok	tiktok_music_trending、tiktok_music_search、tiktok_location_search、tiktok_publishing_settings
私信	send_dm、list_dm_conversations、start_autodm（Instagram 私信，或在 TikTok、YouTube、Facebook、Threads、Bluesky 上公开自动回复）、list_autodms、get_autodm_logs、pause_autodm、resume_autodm、stop_autodm、delete_autodm、manage_autodms
FFmpeg	submit_ffmpeg_job、get_ffmpeg_job、download_ffmpeg_result、get_ffmpeg_consumption
队列	get_queue_settings、update_queue_settings、preview_queue

异步上传会返回一个 request_id。Agent 应轮询 get_status，直到 success: true。

每个问题对应一个工具，而非每个网络对应一个工具

Upload-Post API 并非为每个社交网络都提供一个端点，而是为每个问题提供一个端点，并通过 platform 参数指定要询问哪个平台。get_post_comments、get_post_analytics、get_audience、get_suggestions 和 comment_action 都采用这种方式，因此 Agent 只需学会一种形式，就能在所有网络上复用。只有四个 tiktok_* 工具是特定于网络的，因为它们返回的内容（Commercial Music Library、TikTok 地点、TikTok 每个账户的发布设置）仅存在于 TikTok。

• get_audience — 查看哪些人关注该个人主页、他们所在的位置、在线时间以及会点击哪些内容。还可查看 benchmark_categories，以及设置 benchmarkCategory 时用于比较的细分领域平均值。服务会将时间范围限制为最多 60 天，且截止于今天之前，因此超出范围的请求会被截短，而非拒绝；响应中的 range 会说明实际使用的时间范围。
• get_suggestions — 获取主题标签（包含 view_count）或相关关键词搜索结果，通过 type 区分，而非使用不同的工具。
• get_post_comments — 获取帖子下的顶级评论；指定 commentId 时，则获取其中一条评论下的回复。
• hide_comment、like_comment、pin_comment、edit_comment、hold_comment、approve_comment、ignore_comment、set_post_comments — 每种审核操作对应一个工具。comment_action 通过单个 action 参数执行相同操作，并在除 ChatGPT 以外的所有平台上提供；ChatGPT 只能使用单操作工具（manage_autodms 也一样）。
• comment_action — 在 TikTok（隐藏／点赞／置顶）、Facebook（隐藏／点赞／编辑）、Instagram（隐藏评论，或启用／停用帖子评论）、YouTube（隐藏／暂缓）和 Threads（隐藏／批准／忽略）上审核评论。每个操作值都有对应的反向操作，因此没有任何操作是永久性的。
• get_post_analytics — 获取每条帖子的指标。post_metrics 取决于平台返回的内容，因此结构各不相同：TikTok 还会提供 retention、impression_sources、audience_types、new_followers、reach 和观看时长（average_time_watched、total_time_watched、full_video_watched_rate）。

错误也在各平台之间共用：platform_not_supported（400，附带可响应的网络列表）、invalid_parameter（400）、tiktok_reconnect_required（400）、reauth_required（409）；上游网络发生故障时则返回 502。

TikTok 功能

get_post_comments、create_comment、delete_comment 和 comment_action 接受 platform: "tiktok"，而且 firstComment 在 TikTok 上也像在其他所有平台上一样有效。

TikTok 账号能做什么取决于它的连接方式。list_users 会在每个 TikTok 账号上返回一个 capabilities 数组——music、location、cover_image、cover_timestamp、draft、video_privacy、photo_privacy、profile_analytics、comments、trend_search——每个工具的说明都会注明所需的能力。这些能力会在用户连接 TikTok 时授予，因此，在某项能力推出前就已连接的账号，必须重新连接后才能使用对应工具；tiktok_reconnect_required 错误表示的就是这种情况。

get_media 和 get_cached_post_analytics 使用游标分页：将响应中的 next_cursor 作为 cursor 传回，直到 has_more 为 false。LinkedIn、Discord 和 Telegram 不支持媒体游标，只接受 limit。扫描大量帖子时，优先使用 get_cached_post_analytics，而不是 get_post_analytics——它会重放先前获取的结果，从而避免触及实时分析的速率限制，即每 5 分钟 100 次请求。它仅包含先前通过实时单帖接口获取的帖子；不会在后台刷新，因此 captured_at 是该帖子上次被实时读取的时间。

FFmpeg 任务通过 input_url 接受一个公开 URL，或通过 files 接受多个 URL。任务在 Upload-Post 的编码服务器上运行，每个任务都使用独立的工作目录。full_command 是一次单独的 ffmpeg 调用，其中包含 {input}（或 {input0}、{input1}……）和 {output} 占位符，并且不通过 shell 运行：命令必须以 ffmpeg 开头，且 shell 元字符、..、file: 以及工作目录之外的绝对路径都会被拒绝。轮询 get_ffmpeg_job 直至任务完成，然后调用 download_ffmpeg_result；它会返回结果 URL，而不会通过 MCP 流式传输处理后的二进制文件。只有将该 URL 传给上传工具后，内容才会发布。

执行操作前确认

会以用户身份发布内容或联系他人的工具分两步执行。若调用时未传入 confirmed: true，它们会返回 status: "confirmation_required"，并预览将要发送的确切内容（文本、媒体、平台或收件人、按钮、关键词、时间），但不会执行任何操作；模型会将预览展示给用户，并在用户批准后再次传入 confirmed: true 调用。这适用于 upload_video、upload_photos、upload_text、upload_document、send_dm、reply_to_comment、public_reply_to_comment、create_comment、reply_to_google_business_review、edit_comment、unpublish_post、start_autodm，以及 manage_autodms 中 action: "start" 的情况；当 comment_action / hide_comment 会编辑评论或封禁评论作者时也适用。delete_user 仅会在 confirm_username 与档案名称一致时删除用户。ChatGPT 会在每次写入工具调用前询问用户，因此保留单步工具。

Reddit 应用不可用期间，Reddit 发布功能已关闭：reddit 不会作为平台提供，尝试使用它会报错 reddit_unavailable。恢复后，可自托管用户可以设置 UPLOAD_POST_REDDIT_ENABLED=true。

ChatGPT 视频上传界面

open_upload_studio 会渲染一个 ChatGPT Apps 组件，用于基于文件发布内容：发布一个视频，或一张或多张图片（轮播最多 10 张；传入 mediaType: "photos"）。对于每个文件，组件都会创建一个短时有效的 Upload-Post/R2 暂存上传，将文件直接 PUT 到 R2 并完成上传；每次处理一个文件。随后，组件会按顺序将返回的临时媒体 URL 传给 upload_video 或 upload_photos。对于照片，组件也可以将暂存 URL 交还给 ChatGPT（“发送给 ChatGPT”），由 ChatGPT 自行调用 upload_photos，例如为不同平台设置不同的说明文字。upload_video 和 upload_photos 会拒绝 /mnt/data 和沙盒附件路径，并引导模型使用 Studio。

该组件使用 ChatGPT Apps SDK 桥接，因此只会向 ChatGPT 提供（在 initialize 时通过 clientInfo 检测；可通过 UPLOAD_POST_STUDIO_CLIENTS=<regex> 覆盖匹配规则）。其他所有主机（claude.ai、Claude Desktop、Claude Code、Cursor，等等）都看不到该工具或其 ui:// 资源；而是会向模型提供 create_media_upload / complete_media_upload，并附上逐步操作说明。当客户端无法自行 PUT 文件时，upload_video 会告知助手向用户索取公开 URL，或引导用户前往仪表板。

无论是否使用，暂存对象都会在 24 小时后删除。已安排或排队的帖子仍然安全，因为 upload_video 会在执行前将临时 URL 复制到现有的持久化调度存储中。

Claude 和其他 MCP 客户端也可以不使用 ChatGPT 界面，采用相同的流程：调用 create_media_upload，将文件 PUT 到 upload_url，调用 complete_media_upload，然后将 media_url 传给 upload_video。

当后端 R2 签名 URL 使用的来源与默认值不同时，请在 MCP 主机上设置 UPLOAD_POST_R2_CONNECT_DOMAINS，并以逗号分隔这些来源（例如 https://<account>.r2.cloudflarestorage.com,https://<bucket>.<account>.r2.cloudflarestorage.com），这样 ChatGPT 组件 CSP 才会允许浏览器执行 PUT。

R2 存储桶的 CORS 策略必须允许浏览器上传。限制性策略可以包含实际的组件来源；若要最快完成验证，请使用：

[
  {
    "AllowedOrigins": ["*"],
    "AllowedMethods": ["PUT", "GET", "HEAD"],
    "AllowedHeaders": ["*"],
    "ExposeHeaders": ["ETag"],
    "MaxAgeSeconds": 3600
  }
]

---

本地 / 开发

git clone https://github.com/Upload-Post/upload-post-mcp.git
cd upload-post-mcp
npm install
npm run build

# stdio (default — used by Claude Desktop, Cursor)
UPLOAD_POST_API_KEY=... node dist/index.js

# HTTP streamable (for hosted deployments)
UPLOAD_POST_API_KEY=... node dist/index.js --http --port 8080

使用官方检查器检查实时工具接口：

npx @modelcontextprotocol/inspector node dist/index.js

---

配置

环境变量	模式	默认值	说明
UPLOAD_POST_API_KEY	stdio	—（必填）	单个用户的 Upload-Post API 密钥。在 --http 模式下忽略——密钥随请求提供。
UPLOAD_POST_BASE_URL	两者	https://api.upload-post.com/api	用于可自托管实例或暂存环境的覆盖值。
UPLOAD_POST_MCP_PORT	http	8080	--http 模式的端口。
UPLOAD_POST_MCP_MAX_BODY_MB	http	10	/mcp 请求正文接受的最大大小；超出时返回 413。
UPLOAD_POST_MCP_VALIDATE_API_KEYS	http	true	在为粘贴的 API 密钥开启会话前，使用 GET /uploadposts/me 检查一次（结果会缓存）；被拒绝的密钥会收到 401。
UPLOAD_POST_MCP_KEY_CHECK_TTL_MS	http	600000	已接受的密钥在再次检查前受信任的时长。
UPLOAD_POST_MCP_MAX_SESSIONS	http	2000	内存中保留的活动会话数；超过上限时，空闲时间最长的会话将关闭。
UPLOAD_POST_MCP_MAX_SESSIONS_PER_KEY	http	200	每个凭据对应的活动会话数；超过上限时，该凭据空闲时间最长的会话将关闭。
UPLOAD_POST_MCP_SESSION_TTL_MS	http	1800000	会话关闭前允许的空闲时长。
UPLOAD_POST_MCP_ALLOW_LOCAL_FILES	http	false	允许工具读取服务器磁盘上文件路径中的媒体。共享主机上应关闭（仅接受 http(s) URL）；仅当 HTTP 服务与您自己的文件位于同一环境时才启用。stdio 始终允许使用路径。
OPENAI_APPS_CHALLENGE_TOKEN	http	当前 Upload-Post 验证令牌	可选覆盖值，用于在 /.well-known/openai-apps-challenge 进行 ChatGPT Apps 域名验证。

CLI 标志：

• --http — 启动可流式传输的 HTTP 传输，而非 stdio
• --port <n> — HTTP 模式的端口

HTTP 端点：

• POST /mcp — 通过 MCP 可流式传输的 HTTP 传输进行 JSON-RPC。每个请求都必须携带 Authorization: ApiKey <key>（或 Bearer <key>）。该密钥是用户自己的 Upload-Post API 密钥；服务仅在该会话中使用，不会存储。
• GET /healthz — 存活探针，始终开放。返回 {"ok":true}。

--http 模式下的身份验证模型与 Resend、Tavily、Brave Search 及其他原生使用 API 密钥的服务为其托管 MCP 采用的模式相同：上游密钥就是身份凭据。

---

使用 Docker 部署

此仓库附带多阶段 Dockerfile 和 .dockerignore。在任何支持 Docker 的 PaaS（Fly.io、Railway、Render、Cloud Run、fly machines、自有服务器……）上：

1. 将 PaaS 指向此仓库，并选择 Dockerfile 作为构建包。
2. 端口：8080（与 EXPOSE 8080 匹配）。
3. 环境变量：无需设置。若指向暂存环境，可选设置 UPLOAD_POST_BASE_URL。
4. 健康检查路径：/healthz（HTTP，端口 8080）。
5. 域名：绑定域名，例如 mcp.your-domain.com，并配置 TLS（大多数 PaaS 会通过 Let's Encrypt 自动完成）。

部署后，服务即可供任意数量的用户使用。每位用户都可以使用自己的 Upload-Post API 密钥，将端点添加到 MCP 客户端配置中：

{
  "mcpServers": {
    "upload-post": {
      "url": "https://mcp.your-domain.com/mcp",
      "headers": {
        "Authorization": "ApiKey USER_OWN_UPLOAD_POST_API_KEY"
      }
    }
  }
}

如果没有 Authorization 标头，服务会返回 401。该标头是唯一的凭据——无效的 Upload-Post 密钥会在首次调用工具时显示为上游错误。

在本地测试生产镜像：

docker build -t upload-post-mcp .
docker run --rm -p 8080:8080 upload-post-mcp
curl http://localhost:8080/healthz   # → {"ok":true}
curl -i -X POST http://localhost:8080/mcp \
  -H "content-type: application/json" \
  -d '{}'                               # → 401 (no Authorization)

---

向 Agent 提示的技巧

• 上传时优先使用公共 URL，而不是本地路径——只有在 MCP 服务运行于用户的机器上时，本地路径才有效。
• 在 ChatGPT Apps 中，用户选择视频和图像文件时，优先使用 open_upload_studio。它会先将文件上传到短期有效的 Upload-Post/R2 暂存区，再将临时媒体 URL 传递给 upload_video / upload_photos，从而避免本地路径交接问题。
• 在其他任何客户端中，如果有本地文件：如果客户端可以发送 HTTP 请求（Claude Code、Cursor、脚本），请使用 create_media_upload → 将字节 PUT 到 upload_url → complete_media_upload 暂存文件，然后将返回的 media_url 传递给 upload_video。不具备此功能的托管聊天服务（claude.ai）需要公共 HTTPS URL，或使用 https://app.upload-post.com 上的控制面板。
• 要直接发送视频字节（客户端持有文件而非 URL 时），请将 videoBase64 传递给 upload_video，而不是 videoPathOrUrl。服务端会将其写入临时文件、上传，然后删除该文件。内联字节大小上限为 UPLOAD_POST_MAX_INLINE_MB（默认为 100 MB）；在 --http 模式下，整个请求的大小上限为 UPLOAD_POST_MCP_MAX_BODY_MB（默认为 10 MB，base64 编码后约可容纳 7 MB 视频）——更大的视频请使用公共 URL。
• 发布前，请务必先创建个人资料（create_user），并在 Upload-Post 控制面板中关联社交媒体账号。
• 对于定时发布，请传入包含时区的 ISO 8601 日期，例如 "2026-12-25T10:00:00Z" + "timezone": "Europe/Madrid"。

---

隐私与数据处理

此服务是 Upload-Post API 的无状态代理。每次请求中，它处理的唯一数据是用户的 API 密钥（或解析为 API 密钥的 OAuth 访问令牌）以及正在执行的工具调用参数。MCP 容器本身不会持久化任何用户数据。

• 每次请求接收的内容：Authorization 标头、MCP 工具名称和参数，以及 Agent 传入的任何媒体 URL/路径。
• 转发的内容：代表已验证用户将工具参数转发给 Upload-Post API。
• 存储的内容：不存储任何用户数据。OAuth 令牌存储在 Upload-Post 后端，并经过哈希处理（SHA-256），因此即使令牌存储遭到泄露，也无法冒充用户。
• 记录的内容：HTTP 方法、路径、状态码和不透明的请求 ID。不记录工具参数、API 密钥或令牌。

Upload-Post 完整隐私政策（数据收集、保留、第三方共享、联系方式、GDPR/CCPA）：https://upload-post.com/privacy

如需随时撤销连接器的访问权限，请在 app.upload-post.com 中打开已连接的应用。

---

安全性

• 所有流量都在边缘节点终止 TLS（仅限 HTTPS）。
• 每个请求的 /mcp 都需要有效的 Authorization 标头；OAuth 访问令牌有效期较短（1 小时访问令牌 + 90 天刷新令牌，并根据 RFC 6749 §10.4 进行轮换）。
• 服务会根据允许列表（claude.ai、claude.com、chatgpt.com、chat.openai.com、app.upload-post.com、localhost）验证 Origin 标头，以缓解基于浏览器的客户端遭受 DNS 重绑定攻击的风险。通过自定义仪表板进行自托管时，可使用 OAUTH_EXTRA_ALLOWED_ORIGINS（逗号分隔）扩展允许列表。
• OAuth 元数据同时通过 /.well-known/oauth-protected-resource 和插入路径的形式 /.well-known/oauth-protected-resource/mcp 提供（RFC 9728 §3.1）；oauth-authorization-server 也同样如此。
• 在 --http 模式下，服务会针对每个失败请求以及每个 OAuth/.well-known 请求向 stderr 写入一行日志（包含方法、路径、状态、认证方案、用户代理；绝不包含查询字符串或凭据）。设置 UPLOAD_POST_MCP_ACCESS_LOG=all 可记录所有请求；设置为 off 可禁用日志。
• 如果 ChatGPT 在 OAuth 期间显示 redirect_uri not on allow-list，请将失败的授权请求中的确切 redirect_uri 添加到 Upload-Post 后端的 OAuth 重定向允许列表中。对于 ChatGPT 客户端，该 URI 通常为 https://chatgpt.com/.../oauth/callback 或 https://chat.openai.com/.../oauth/callback。
• 已预先允许以下 OAuth 重定向回调：Claude（claude.ai/claude.com）、ChatGPT、Cursor、VS Code（稳定版 + Insiders）、Smithery、Glama、Toolhouse、Perplexity（标准版 + Enterprise）、Mistral Studio 调试器和 Postman；以及任意 http://localhost/环回重定向（RFC 8252），涵盖 Claude Code、Windsurf、Cline、Continue、Goose、Gemini CLI 和其他 mcp-remote 风格的客户端。对于没有公开固定回调地址的平台（例如 Grok、Le Chat 生产版），可按需添加。
• 所有工具都会声明 MCP readOnlyHint/destructiveHint 注解，以便客户端在执行破坏性操作时显示确认提示；发布内容或向他人发送消息的工具还要求显式设置 confirmed: true（参见操作前确认）。

报告安全问题：[email protected]（可按需提供加密 PGP）。

---

许可证

MIT © Upload-Post