Skip to main content
Glama
techdou

Remotion Video MCP Server

by techdou
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Remotion Video — Agent 驱动的视频生成项目服务

从 SRT 字幕到完整 Remotion 视频的端到端工作流。支持 MCP 驱动、多 Provider TTS 语音合成、异步任务队列、实时 Web 控制台。

Provenance | 来源：改编自 B 站 YangAgent 分享的 Remotion 视频生成方案，在原工作流基础上重构为 MCP + 异步队列架构。

TypeScript MCP SQLite License: MIT

架构

用户 → ZCode / Codex / Claude Code → Skill (SKILL.md)
                                         ↓
                                   MCP Server (17 工具, stdio)
                                         ↓
                                  Domain Service (Express + SSE)
                                         ↓
                             Core (SQLite + Provider + Artifact + Run 队列)
                                         ↓
                           scripts/*.js + tts/*.py + Remotion CLI
                                         ↓
                                    Web 控制台 (React SPA)

四层分离：

层

目录

职责

Skill

SKILL.md + references/

触发条件、工作流编排、质量标准

MCP Server

server/mcp/

17 个 MCP 工具，Agent 通过 stdio 调用

Domain Service

server/api/ + server/core/

Express API + SSE + SQLite + 异步队列 + Worker

Provider

server/core/providers/

封装 scripts/.js / tts/.py / Remotion CLI

Related MCP server: hyper-video-service

快速开始

安装

git clone https://github.com/techdou/remotion-video.git
cd remotion-video

# 安装后端依赖
npm install

# 安装前端依赖
cd web-ui && npm install && cd ..

# 安装模板依赖（首次）
cd template && npm install && cd ..

构建

# 构建后端（TypeScript → dist/）
npm run build

# 构建前端（JSX → app.js）
npx esbuild web-ui/public/app.jsx --bundle --format=iife --jsx=transform \
  --outfile=web-ui/public/app.js

启动

# 启动 Domain Service（API + Worker + Web 控制台）
node dist/index.js
# → http://127.0.0.1:3210

# 启动 MCP Server（另一个终端，供 Agent 调用）
node dist/mcp.js

核心能力

MCP Server（17 个工具）

Agent 通过 MCP 协议调用以下工具，所有长任务异步执行（立即返回 runId）：

工具

用途

get_project_context

获取项目完整上下文（project + runs + artifacts）

get_capabilities

列出 Provider 能力和支持的 run 类型

start_run

提交异步任务（init/render/tts/validate 等）

get_run_status

查询任务状态和进度

cancel_run

取消运行中的任务

list_artifacts

列出项目产物

set_artifact_status

设置产物状态（draft→candidate→selected→final）

test_provider

测试 Provider 连通性

...

完整 17 个工具见 server/mcp/index.ts

异步 Run 队列

  • SQLite-backed：任务持久化，进程崩溃不丢失

  • Worker Lease + Heartbeat：防止任务被重复执行

  • 崩溃恢复：启动时扫描超时 run，自动标记 failed 或重新排队

  • AbortSignal：取消信号贯穿 Provider → 子进程 → 下载 → 重试

Provider 系统

三种 Provider 封装现有脚本，通过子进程 spawn 调用（不修改原脚本）：

Provider

包装对象

操作

script

scripts/*.js (CommonJS)

init / storyboard / creators / registry / validate

tts

tts/*.py (Python)

tts（语音合成）/ merge_speech（合并音轨）

render

npx remotion render

render（视频渲染）

TTS 语音合成（3 个 Provider）

Provider

平台

配置

openai (默认)

OpenAI / 硅基流动 / 火山方舟 / OneAPI

TTS_API_KEY + TTS_BASE_URL

mimo

小米 MiMo

MIMO_API_KEY（Chat Completions 格式）

edge

Edge TTS

免费本地，无需 API Key

配置见 .env.example。时间轴策略：SRT 驱动，每段语音放在原始时间点。

Artifact 系统

每个产物记录：ID、类型、状态（draft→candidate→selected→final→archived）、来源 Run、父 Artifact（版本树）。

Web 控制台

多页面 SPA，学者暖色系设计（亚麻 #F5F3EE + 陶杯 #C0785A + 衬线字体）：

  • 控制台：项目统计、活跃任务、最近项目

  • 项目：项目列表 + 新建

  • 项目工作区：Pipeline 步骤 / 产物版本 / 任务记录（三标签页）

  • Provider：能力列表 + 连通性测试

  • 设置：TTS 配置管理

目录结构

remotion-video/
├── server/                      # TS 业务内核
│   ├── core/
│   │   ├── types.ts             # 接口定义
│   │   ├── db.ts                # SQLite + WAL + migration
│   │   ├── storage.ts           # CRUD + revision 乐观锁
│   │   ├── run-queue.ts         # 异步队列 + Worker + 崩溃恢复
│   │   ├── artifact-store.ts    # 产物文件存储 + 版本管理
│   │   ├── config.ts            # .env 读取 + 脱敏 + 路径防护
│   │   ├── providers/           # Provider 系统
│   │   │   ├── base.ts          # 接口
│   │   │   ├── script-provider.ts
│   │   │   ├── tts-provider.ts
│   │   │   ├── render-provider.ts
│   │   │   └── registry.ts
│   │   ├── migrations/          # SQL 迁移
│   │   └── tests/               # 34 个测试
│   ├── mcp/index.ts             # MCP Server (17 工具)
│   ├── api/index.ts             # Express API + SSE
│   └── index.ts                 # 主入口
├── web-ui/                      # React 控制台
│   ├── public/
│   │   ├── app.jsx              # 源码（需编译）
│   │   ├── styles.css
│   │   └── vendor/              # React 18 本地化
│   └── ...
├── scripts/                     # 工作流脚本 (CommonJS)
├── tts/                         # TTS Python 子系统
│   ├── generate-speech.py
│   ├── merge-speech.py
│   └── providers/               # openai / mimo / edge
├── template/                    # Remotion 项目模板
├── rules/                       # 40+ Remotion 最佳实践规则
├── references/                  # 工作流协议文档
├── SKILL.md                     # Agent 技能定义
├── .env.example                 # TTS 配置模板
├── tsconfig.json
└── tsup.config.ts

测试

# 运行全部 34 个测试
npx tsx --test server/core/tests/storage.test.ts server/core/tests/advanced.test.ts

覆盖：Project CRUD、Run 生命周期、Artifact 版本树、revision 乐观锁并发、Worker lease/heartbeat、崩溃恢复、Provider 能力探测和错误处理。

安全

  • 绑定 127.0.0.1：Domain Service 不暴露局域网

  • 路径穿越防护：validateProjectPath 精确匹配项目目录

  • API Key 脱敏：GET 返回 sk-abc***，PUT 跳过脱敏值

  • CORS 限制：仅允许 localhost

  • 配置合并写入：保留 .env 注释，key 格式校验，拒绝换行注入

依赖

依赖

用途

Node.js 18+

运行环境

Python 3.9+

TTS 子系统

ffmpeg

语音合并

better-sqlite3

SQLite 驱动

@modelcontextprotocol/sdk

MCP Server

express

HTTP API

edge-tts (可选)

免费 TTS

License

MIT © 2026 techdou

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers