video-gateway-mcp

一个独立的 MCP（Model Context Protocol）服务，用于调用中转站的视频生成大模型（如 doubao-seedance-1-5-pro_480p、kling-identify-face）。

通过 stdio 传输，可被任意支持 MCP 的客户端（Claude Desktop / Cline / Cursor / 自研 Agent 等）接入。

支持的模型

• doubao-seedance-1-5-pro_480p —— 豆包 Seedance 文生视频 / 图生视频（当前 token 可用）
• kling-identify-face —— 可灵保持人脸身份（注意：当前 token 返回 403 无权限）

实际可用模型以中转站 /models 返回及 token 权限为准，可用 list_video_models 工具查询。

中转站协议（实测要点，已端到端验证出片）

• 视频端点：POST {API_BASE_URL}/video/generations（注意是 /video/ 单数，JSON 会被拒，必须 multipart/form-data）
• 时长字段名必须是 seconds（不是 duration！用 duration 会被 relay 错映射到 Gemini 的 contents[0].text.duration，上游报 "the specified duration is not supported"）
• doubao-seedance-1-5-pro 仅支持 4~12 秒（seconds 传字符串数字，实测 5 秒成功出片）
• 异步任务：提交返回 task_id，轮询 GET {API_BASE_URL}/video/generations/{id} 或 GET {API_BASE_URL}/video/tasks/{id} 状态在 data.status（queued→in_progress→success），视频地址在 data.fail_reason（字段名有误导性，实际就是视频 URL）
• 上游通道有熔断器：连续出错会暂时返回 503 channel_circuit_open，稍后自动恢复。

安装与运行

cd video-mcp
npm install
npm run build      # 编译到 dist/
npm start          # 启动 stdio 服务
# 或者开发模式： npm run dev

配置（.env）

复制 .env.example 为 .env 并填入：

API_BASE_URL=https://api.geeknow.ai/v1
API_KEY=你的密钥

.env 已在 .gitignore 中，不会提交。

工具列表

list_video_models

列出中转站当前可用视频模型及目标模型可达性。

generate_video

生成视频，参数： | 参数 | 说明 | 默认 | |---|---|---| | model | 视频模型 | doubao-seedance-1-5-pro_480p | | prompt | 内容描述（必填） | — | | image | 图生视频参考图：http(s) 链接或本地图片绝对路径 | — | | duration | 时长（秒），内部转为 seconds 字段；仅支持 4~12 秒 | 12 | | size | 分辨率，如 832x480 | 模型决定 | | resolution | 分辨率档位 480p/720p/1080p | — | | aspect_ratio | landscape/portrait/square | — | | n | 生成数量（≤4） | 1 | | output_dir | 本地保存目录 | ./generated-videos | | poll_timeout_sec | 轮询超时 | 300 | | poll_interval_sec | 轮询间隔 | 10 |

返回：完成后视频下载到 output_dir，返回本地文件路径与任务状态；失败/超时会返回上游原始错误信息。

客户端接入示例（claude_desktop_config.json）

{
  "mcpServers": {
    "video-gateway": {
      "command": "node",
      "args": ["/绝对路径/video-mcp/dist/index.js"],
      "env": {
        "API_BASE_URL": "https://api.geeknow.ai/v1",
        "API_KEY": "你的密钥"
      }
    }
  }
}

（也可以把 env 去掉，改用 video-mcp/.env 文件。）

通过 npm 发布 / 安装使用（分享给其他 agent）

本服务可发布为 npm 包 video-gateway-mcp。包内不包含 .env（密钥不随包分发），使用方必须通过 MCP 配置的 env 注入 API_BASE_URL 与 API_KEY。

方式 A：npx 直接运行（推荐，免安装）

{
  "mcpServers": {
    "video-gateway": {
      "command": "npx",
      "args": ["-y", "video-gateway-mcp"],
      "env": {
        "API_BASE_URL": "https://api.geeknow.ai/v1",
        "API_KEY": "你的密钥"
      }
    }
  }
}

方式 B：全局安装后使用

npm install -g video-gateway-mcp

{
  "mcpServers": {
    "video-gateway": {
      "command": "video-gateway-mcp",
      "env": {
        "API_BASE_URL": "https://api.geeknow.ai/v1",
        "API_KEY": "你的密钥"
      }
    }
  }
}

说明：代码中 dotenv.config({ path: .../.env }) 的逻辑是「环境变量已存在则用之，否则读包目录 .env」。因此通过 env 注入密钥即生效，无需在包目录放 .env。

发布到 npm

npm login      # 先登录你的 npm 账号
npm publish    # 发布（包名 video-gateway-mcp，公开）

发布前可用 npm pack 生成本地 tgz 预览内容（应仅含 dist / README.md / package.json，不含 .env、node_modules、generated-videos）。