VideoGen

@videogen/mcp

一个 Model Context Protocol（MCP）服务，可向任何 MCP 客户端（Cursor、Claude Desktop、Windsurf 等）提供完整的 VideoGen API。你的 Agent 可以根据脚本生成视频，制作图片 / 配音 / 音乐 / 虚拟形象，上传文件，导出和混剪项目，以及管理运行任务——所有操作都使用你自己的 API 密钥进行身份验证。

详细了解 VideoGen MCP 服务。

在 Smithery 上查找托管服务。

ChatGPT

托管插件包含一个 VideoGen 首页侧边栏应用（open_home）。它与产品首页一致：常规创作提示词和建议、近期项目、示例类别、精选工作流、可重复使用的素材和模板。浏览不会启动生成；点击 Start 会将草稿发送到 ChatGPT 对话中。项目和素材库链接会打开相应的 VideoGen 环境。

首页目录由与 frontend/ 相同的辅助程序生成，并提交到 web/homeCatalog.ts，使独立的 MCP/npm/Docker 构建不依赖内部软件包。更改产品目录后，请在仓库根目录运行 cd api && node --import tsx scripts/generate-chatgpt-home.ts 刷新目录（需使用当前的 base/defs/static JS 构建）。build:js 会将页面与现有的上传和预览组件一同打包。部署 MCP 并重新扫描现有插件后，ChatGPT 中才会显示侧边栏入口。

首页专项检查（无需浏览器或在线账户）：

cd mcp
node --import ./test/register.mjs --test src/homeWidget.test.ts test/homeBridge.test.mjs
cd ../api
TSX_TSCONFIG_PATH=../mcp/web/tsconfig.json node --import tsx --test ../mcp/test/homePage.test.tsx

使用 ChatGPT 插件目录中的公开 VideoGen 插件。这是所有用户在 ChatGPT 中使用 VideoGen 的受支持方式。

/mcp/chatgpt 端点、ChatGPT Apps 交易说明、open_uploader 组件以及本文后面的连接器清单，均用于该插件的内部测试。

该服务支持两种传输方式。除内部测试用的 ChatGPT Apps 界面外，工具集相同（见上文）：

• 本地（stdio） — 客户端将 @videogen/mcp 作为子进程启动，并从 VIDEOGEN_API_KEY 读取密钥。
• 远程（Streamable HTTP） — 托管的多租户 HTTP 服务。客户端通过网络连接，并在每个请求中使用 Authorization: Bearer <api-key> 进行身份验证；服务器上不会保存密钥。

托管界面（远程）： /mcp（以及 stdio）是标准界面：当用户的点数用尽或需要套餐功能时，工具和指引会引导他们使用 get_app_deep_link（OPEN_UPGRADE / OPEN_PURCHASE_CREDITS / OPEN_ENABLE_TOP_UPS）。/mcp/chatgpt 是面向公开插件的 ChatGPT Apps 内部测试界面：此处会省略上述交易深层链接，将账单错误改写为“管理你的 VideoGen 账户”，且文案不会提及 purchase / buy / upgrade / top-ups（OpenAI 插件数字商品政策）。请参阅 .cursor/rules/chatgpt-mcp-no-commerce.mdc 和 mcp/src/hostSurface.ts。

这与托管的文档 MCP（地址为 https://docs.videogen.io/_mcp/server）不同，后者只允许客户端阅读 API 文档。此服务则会实际 执行 API。

工作原理

• 封装官方 @videogen/sdk，并通过 SDK 的认证透传功能调用实时 API。
• 本地传输从 VIDEOGEN_API_KEY 读取密钥；远程传输从每个请求的 Authorization: Bearer 标头读取密钥，并为该团队创建一个全新的、按请求绑定的服务（无状态——请求之间不共享会话状态）。
• 除了发送给 VideoGen API 的请求外，密钥不会离开你的设备（本地）；远程模式下，密钥仅在请求期间转发给 VideoGen API，且不会持久化。
• 长时间运行的操作（工作流、媒体工具、项目导出）使用复合工具。托管的 HTTP 传输会立即返回运行／执行 ID；使用相应的 get_* 工具继续轮询。默认情况下，本地 stdio 传输会等待操作完成。

配置

从 app.videogen.io/api 获取 API 密钥。两种传输方式提供相同的工具；推荐使用远程服务。

远程（Streamable HTTP）——推荐

无需安装或更新。将支持 Streamable HTTP 传输的任意 MCP 客户端指向托管端点，并将 API 密钥作为 bearer token 发送：

{
  "mcpServers": {
    "videogen": {
      "url": "https://mcp.videogen.io/mcp",
      "headers": {
        "Authorization": "Bearer sk_videogen_live_..."
      }
    }
  }
}

远程服务：

• 通过 POST /mcp 接受 MCP JSON-RPC 消息（无状态——每个请求都会创建一个全新的服务）。
• 从 Authorization: Bearer 标头读取 API 密钥或 OAuth 访问令牌。标准 /mcp 端点要求每个请求都提供凭据，并返回带有 WWW-Authenticate 挑战的 401，以启动 OAuth。内部测试用的 /mcp/chatgpt 端点无需身份验证即可提供工具发现，并会在受保护的工具结果中返回 OAuth 挑战，因为 ChatGPT 不会根据标准传输挑战启动 OAuth。凭据仅转发给 VideoGen API，不会存储。
• 提供 GET /health，供负载均衡器／Cloud Run 启动探针使用。
• 处理 CORS 预检（OPTIONS），以便基于浏览器的客户端连接。
• 支持三种上传方式。对于较小的资源（图像、徽标、短音频），upload_file 会以内联方式接收 base64 编码的内容（fileData）。对于较大的文件，create_file_upload 会返回 { fileId, uploadUrl }；客户端将原始字节 PUT 到这个短时有效的预签名 URL（无需 Authorization 标头），然后调用 get_file 并传入 { fileId, wait: true } 等待处理完成。在内部测试用的 /mcp/chatgpt 界面上，open_uploader 会显示聊天内上传组件，供用户直接选择文件；也可以传入用户已附加的照片（files）。上传组件本身会调用 create_file_upload，在客户端通过 PUT 上传字节，并且只返回最终生成的 vg_file_... ID，因此预签名 URL 不会暴露给模型。在该界面上，upload_file 和 create_file_upload 对模型隐藏（ui.visibility 仅限 app）：文件名不会上传 ChatGPT 附件，服务也不会获取附件 URL。无论哪种方式，你都会获得可传递给其他工具的 vg_file_... ID。本地（stdio）服务则通过本地 filePath 上传。（服务绝不会获取调用方提供的 URL，因此不存在 SSRF 攻击面。）

本地（stdio）——Cursor / Claude Desktop

作为子进程运行，由客户端使用 npx 启动。从 VIDEOGEN_API_KEY 环境变量读取 API 密钥；除发送给 VideoGen API 的请求外，密钥不会离开你的设备：

{
  "mcpServers": {
    "videogen": {
      "command": "npx",
      "args": ["-y", "@videogen/mcp"],
      "env": {
        "VIDEOGEN_API_KEY": "sk_videogen_live_..."
      }
    }
  }
}

环境变量

变量	必需	默认值	描述
VIDEOGEN_API_KEY	仅本地	—	你的 VideoGen API 密钥（本地服务）。在远程服务上，密钥会通过 Authorization 标头传递。
VIDEOGEN_BASE_URL	否	https://api.videogen.io	覆盖上游 API 基础 URL（例如用于本地开发）。适用于两种传输方式。未设置时，远程服务会根据部署环境（dev/prerelease/prod）解析上游 API；本地运行默认使用公开的 prod API。
VIDEOGEN_OAUTH_ISSUER	否	—	仅适用于远程服务。完整的 OAuth 2.1 issuer URL。设置此变量（或根据下方变量推导）后，服务会公布 OAuth 受保护资源元数据（RFC 9728）以及 resource_metadata 401 挑战，以便 MCP 客户端发现授权服务器并完成账户关联。必须与上游 API（VIDEOGEN_BASE_URL）用于验证令牌的 issuer 匹配。
VIDEOGEN_OAUTH_SUPABASE_PROJECT_URL	否	—	仅适用于远程服务。Supabase 项目基础 URL；issuer 会推导为 ${url}/auth/v1。设置了 VIDEOGEN_OAUTH_ISSUER 时，此变量会被忽略。
VIDEOGEN_OPENAI_APPS_CHALLENGE_TOKEN	否	—	仅适用于远程服务。供内部测试使用的 OpenAI Plugins / ChatGPT Apps 公共插件域名验证令牌。设置后，GET /.well-known/openai-apps-challenge 会以 text/plain 返回该确切值。未设置时，该路径会返回非 JSON-RPC 404。

工具

有关 50 个线上托管工具，请参阅可调用工具参考和完整的输入/输出 JSON 架构。架构快照取自 MCP tools/list；请在已连接的服务上使用发现功能获取最新定义。

工作流（端到端视频）

script_to_video、voiceover_to_video、slideshow_to_video、storyboard_to_video、list_workflow_runs、get_workflow_run、cancel_workflow_run

媒体工具

generate_image、generate_video_clip、text_to_speech、generate_sound_effect、generate_music、generate_avatar、vectorize_image、remove_image_background、remove_video_background、upscale_image、upscale_video、image_3d_effect、list_tool_executions、get_tool_execution、cancel_tool_execution

项目

list_projects、get_project、export_project、get_project_export、remix_project、list_project_remix_actions

文件

upload_file、create_file_upload、get_file、list_files、open_uploader

open_uploader 是 internal-testing /mcp/chatgpt 界面上的一个小组件（仅适用于远程服务）：它会渲染聊天内的文件选择器（作为 MCP UI 资源提供的 React 组件），让 ChatGPT 用户无需粘贴链接即可附加文件。将聊天中已附加的照片作为 files 传入。不渲染 MCP Apps UI 的客户端会忽略此工具；这些客户端应改用 upload_file / create_file_upload。ChatGPT 用户应使用公开的 VideoGen 插件。

实体

list_entities、create_entity、get_entity、update_entity、archive_entity、add_entity_reference、remove_entity_reference

创建 ACTOR / PRODUCT / VISUAL_STYLE 实体，附加已上传的图像引用，然后将 vg_enti_... ID 传入工作流和 generate_avatar（actorEntityId；在 storyboard_to_video 中，则按场景传入 productEntityIds / actorEntityIds / visualStyleEntityId）。

资源与账户

list_tts_voices、list_languages、get_me、get_app_deep_link

指南（面向 Agent 的文档）

通过 MCP 资源和镜像工具公开的操作手册（无需 API 凭据）：

资源 URI	镜像工具
guidance://getting-started	get_getting_started_guidance
guidance://async-tasks	get_async_tasks_guidance
guidance://workflows	get_workflows_guidance
guidance://tools-vs-workflows	get_tools_vs_workflows_guidance

在进行重要设置、轮询、工作流／混剪／导出操作，或作出工具与工作流之间的选择前，请先调用匹配的 get_*_guidance 工具。许多宿主不会自动附加资源；使用工具是可靠的获取方式。内容以 docs.videogen.io 上的公开文档为依据，但针对 MCP 工具用法编写（包括托管环境中的等待时限）。

创意类 MCP 工具呈现的是用户意图，而不是较底层的开发者 API 请求格式。使用 style 提供完整、严格的视觉风格段落，依次描述媒介、质感、调色板，然后锁定简单构图；使用 aspectRatio（{ width, height } 单位，例如 { width: 16, height: 9 }）设置输出尺寸。省略工作流风格时，将使用应用的 Realistic 外观（Photorealistic photograph, natural lighting）。不要传入 watercolor 这类简短标签。除非风格要求画面简单，否则图像模型会在画面中填满文字、图表和示意图。remix_project 接受精选的 edits：CAPTIONS、TRANSITIONS、CONVERT_IMAGES_TO_VIDEOS 和 ZOOM。CONVERT_IMAGES_TO_VIDEOS 会根据静态图像生成 AI 视频片段（成本较高）。ZOOM 是成本较低的 Ken Burns 镜头运动。未公开 watermarkMode 和 endScreenMode；MCP 始终发送 AUTO（Free 计划的输出包含 VideoGen 水印；VideoGen Pro 会移除水印）。

工作流、媒体生成和导出工具会启动操作并在内部轮询。在托管（Streamable HTTP）服务上，等待时长受 Cloudflare 代理超时限制，因此较长的生成任务会返回仍在运行的快照，而不是 524。请使用 get_tool_execution、get_workflow_run 或 get_project_export 继续轮询。

对于 generate_avatar，请提供 audioFileId，并通过 actorEntityId 指定一个 ACTOR 实体。可将 avatarQuality 设置为 LOW、STANDARD、HIGH 或 MAX。script_to_video、slideshow_to_video 和 CHANGE_NARRATOR 接受相同的可选演员字段。

所有工具的参数及其 REST 端点映射，请参阅完整工具参考。

开发

pnpm build           # bundle to dist/ (dist/index.js, dist/http.js, and the widget)
pnpm typecheck       # type-check
pnpm lint:fix        # lint

# Smoke test the local (stdio) server:
VIDEOGEN_API_KEY=sk_videogen_live_... node dist/index.js

# Smoke test the remote (HTTP) server:
PORT=8080 node dist/http.js
#   Health:  curl http://localhost:8080/health
#   MCP:     curl -X POST http://localhost:8080/mcp \
#              -H 'Authorization: Bearer sk_videogen_live_...' \
#              -H 'Content-Type: application/json' \
#              -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

VIDEOGEN_BASE_URL 可为两种传输方式覆盖上游 API（例如，开发期间可指向本地 API）。

部署（远程服务）

远程服务通过标准 monorepo CI/CD 部署到 Cloud Run，与 api / backend / external / frontend 一同部署：

• 镜像：ci-cd/docker/mcp/Dockerfile — 精简的多阶段 Node 构建（不包含 ffmpeg / gcloud / VPC 工具；服务只会向其对应环境的 VideoGen 开发者 API 发起出站 HTTPS 调用：dev.api.videogen.io / prerelease.api.videogen.io / api.videogen.io，这些地址均已存在）。
• **服务注册表：**在 ci-cd/utils.ts（CLOUD_RUN_SERVICES）中注册了 mcp。
• 构建配置：ci-cd/config.build.ts（CLOUD_RUN_SERVICE_TO_BUILD_CONFIG_MAP.mcp）。
• 部署配置：ci-cd/config.deploy.ts（mcp）——1 CPU / 2 GiB、并发数 80、60m 请求超时（工具调用会对工作流／导出进行长轮询）、allowUnauthenticated: true（按请求使用调用方的 API key 进行身份验证，而非通过 GCP IAM 验证）。
• 生成的流水线：ci-cd/cloudbuild/mcp.build.yaml 以及 GitHub 构建／部署工作流矩阵中的 mcp 条目均由 CI/CD 生成器生成。更改构建／部署配置后，请重新生成这些文件（不要手动编辑）。

手动执行的 GCP 步骤（一次性）

CI/CD 会构建并部署 Cloud Run 服务，但首次使用时，必须在 GCP 中手动完成几个步骤：

1. 自定义域名 / DNS。 服务会立即通过生成的 *.run.app URL 提供访问。要通过 mcp.videogen.io 提供服务，请创建 Cloud Run 域名映射（或将其添加到现有负载均衡器后面），并添加相应的 DNS 记录。域名解析后，更新上方客户端配置中的 url。
2. 验证首次部署。 首次成功部署后，确认 GET https://<service-url>/health 返回 200，并确认携带有效 bearer token 的 POST /mcp 会列出工具。

ChatGPT 连接器（OAuth）检查清单（内部测试）

此检查清单供 VideoGen 工程师测试公开的 VideoGen 插件。用户可从 ChatGPT 插件目录安装该插件。

为某个环境部署远程 MCP 服务后（例如 DEV → https://dev.mcp.videogen.io/mcp）：

1. 确认发现机制和身份验证模式：
   • GET https://<mcp-host>/.well-known/oauth-protected-resource/mcp 返回 200，其中 resource 以 /mcp 结尾，且 authorization_servers 等于 MCP 源站（不含路径——Cursor 的变通方案）。
   • GET https://<mcp-host>/.well-known/oauth-protected-resource/mcp/chatgpt 返回 200，其中 resource 以 /mcp/chatgpt 结尾，且 authorization_servers 等于 Supabase Auth 颁发者（…/auth/v1）。
   • GET https://<mcp-host>/.well-known/oauth-authorization-server 返回 200，其中 issuer 等于 MCP 源站，authorize/token/register 端点位于 Supabase Auth。
   • npx -y @modelcontextprotocol/[email protected] --cli https://<mcp-host>/mcp/chatgpt --transport http --method tools/list 会列出约 35 个或更多工具（包括标记为 noauth 的 open_uploader 和标记为 oauth2 的 API 工具）。
   • 对 /mcp 的所有匿名 POST 请求（包括 initialize 和 tools/list）都会返回 HTTP 401 + WWW-Authenticate，以便 Cursor / Claude 立即启动 OAuth。
   • 对 /mcp/chatgpt 进行匿名 tools/call get_me 请求会返回 HTTP 200，并在工具结果中包含 _meta["mcp/www_authenticate"] 挑战（ChatGPT）。
2. 在 ChatGPT 应用中（例如 VideoGen (DEV)），将 MCP URL 设置为 https://<mcp-host>/mcp/chatgpt（而不是 /mcp）。将确切的 OAuth 回调 URL（https://chatgpt.com/connector/oauth/{callback_id}）复制到该环境的 Supabase Auth OAuth 客户端重定向允许列表中。
3. 在 ChatGPT 连接器构建器中优先使用 DCR（Supabase 会公布 registration_endpoint；不会公布 CIMD / client_id_metadata_document_supported）。ChatGPT 通过 DCR 为我们的应用注册客户端后，将确切的 client_id 添加到 core/src/logic/oauth/trustedOAuthClientIds.ts 中的 TRUSTED_OAUTH_CLIENT_IDS，使同意屏幕将其视为已验证。
4. 在 ChatGPT 设置中，依次选择该应用 → 刷新 → 扫描工具 → 按提示完成 OAuth。
5. 开始一个新对话，从工具菜单中选择该应用，并调用一个读取工具（例如 get_me）。元数据变更后，不要复用旧聊天。

STANDARD_TESTS 会通过 mcp-http 自动对 /mcp/chatgpt 执行匿名 ChatGPT 发现测试（pnpm --filter @videogen/api mcp:test -- --transport http --env <env> --server-mode remote）。该命令会在经过身份验证的完整冒烟测试之前调用 Inspector CLI，并断言 open_uploader 标记为 noauth，且 API 工具标记为 oauth2。如果主机尚未重新部署这些元数据，此方案检查就会失败。