Xiangsu MCP
Provides integration with Douyin Xiangsu (像塑), ByteDance's effect creation editor, enabling AI agents to edit scenes, manage resources, develop and compile scripts, preview and save projects, and use official image, audio, and workflow generation capabilities.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
像塑 MCP
让 AI Agent 通过 MCP 操作抖音像塑:编辑场景、开发脚本、编译、预览、保存,以及调用官方图片、音频和工作流能力。
建议优先使用官方 MCP。 像塑已提供官方 MCP,请先使用编辑器提供的安装提示词配置官方接入,后续跟随像塑更新。像塑官网 · 官方更新日志
如果官方 MCP 接入出现问题或你的客户端需要 stdio 接入,或需要本项目保留的试玩状态读取、音频检测输入模拟和旧工具接口,再考虑使用本项目。这是独立社区项目,后续以低频适配和必要修复为主。
当前版本:0.3.0。 历史版本见 Releases;使用历史版本时,请同时阅读该版本自带的 README。
版本对应与兼容规则
从 0.3.0 起,每个 MCP 版本以本次实际验证的像塑版本为下限,只覆盖该版本及更新版本,不支持更旧版本。
等于验证基线:允许使用,已实测范围见下表和验证记录。
高于验证基线:允许使用并提示未实测;不保证未来像塑更新不会改变接口。
低于验证基线:校验拒绝。请升级像塑,或从 历史 Releases 选择适配旧像塑的 MCP。
例如,MCP 0.3.0 允许像塑 9.7.2 及以后版本;9.7.1、9.6.x、9.5.x 不能通过本版校验。
MCP 版本 | 对应的实际验证版本 | 版本校验范围 | 验证重点 |
0.3.0 | 9.7.2.918909817 | 9.7.2 及以后;更高版本标记为未实测 | 场景编辑、脚本挂载与编译、真实预览、保存,图片和短音频生成并导入;更新记录 |
9.5.2.887097048 | 历史规则:9.4.0 及以后允许安装 | 会话绑定、文字布局与批次预检、截图、编译、录制;验证记录 | |
9.4.1.872531341;保留 9.4.0 的历史验证 | 历史规则:9.4.0 及以后允许安装 | 场景、脚本、资源绑定、试玩状态、音频模拟与动作;验证记录 | |
9.4.0.866073534 | 仅接受当时审计过的 9.4.0 安装包 | 场景、脚本、预览、交互和运行库恢复;验证记录 |
历史发布版保留发布时的校验规则,不追溯改写。允许安装不等于完成实测;旧版的成功记录也不自动成为新版全部功能的验证结果。
Related MCP server: PlayCanvas Editor MCP Server
功能与验证范围
功能 | 可用内容与实测状态 |
场景与脚本 | 编辑对象、管理资源、开发脚本。9.7.2 已验证对象编辑、脚本挂载、编译及日志 |
预览与保存 | 切换预览输入、截图、交互和保存工程。9.7.2 已验证真实预览、启动日志和保存 |
图片与音频 | 单项或批量生成素材并导入。9.7.2 已真实生成并导入 1 张图、1 段短音频 |
AI 工作流 | 编辑工作流、生成并下载结果。已实测能力查询;完整编辑与生成流程尚未实机验证 |
H5 脚本动画 | 导入脚本动画、查询状态和渲染参数。已实测参数读取及产物发布;完整导入和云端视频尚未端到端验证 |
试玩与音频输入模拟 | 读取运行状态、模拟动作和音频检测输入。9.4.0/9.4.1 有核心实测;9.7.2 尚未重跑整套试玩回归 |
本地辅助工具 | 工程文件读写、图片裁剪压缩、静态 SVG 转 PNG、TypeScript 符号查询 |
当前 37 项自动测试通过,实机验证范围见更新记录。
使用时还需注意:
图片、音频和工作流功能需要像塑官方 MCP 服务可用;云端生成使用像塑登录状态和账号额度,只按用户授权提交。
国际版 TikTok Effect House、macOS、复杂材质/物理/预制件和全部原生命令组合尚未验证。多步操作可能部分完成,失败或超时后先读回,不自动重放写入。
安装本项目
以下步骤适用于 0.3.0。
让 Agent 安装
把工程总目录改为自己的路径,再复制下面的提示词:
请安装并配置本仓库的 Xiangsu MCP:https://github.com/sleepyquq/xiangsu-mcp
先读 README.md 和 docs/SKILL-ADAPTER.md,核对取得的源码版本与像塑版本。复用本机已有仓库,或克隆到合适的工具目录;检查 Windows、PowerShell 7、Git、Node.js 24,安装依赖并运行 npm test。
设置 XIANGSU_EFFECT_WORKSPACE 后运行 node scripts/install.mjs;像塑不在默认位置时设置 XIANGSU_EDITOR_ROOT。遵守所选 MCP 版本的最低像塑版本限制,更高但未实测版本可继续,低于下限时不要绕过校验。
保留客户端已有配置,添加 xiangsu-editor stdio 服务,使用 node 和 src/server.mjs 的绝对路径。安装插件后如需重开工程,先告诉我保存工作,不要擅自重启。重新连接 MCP 后,核对测试工程并只读确认连接;不要自动修改工程或提交付费生成。
我的特效工程总目录:D:/Effects(请替换)1. 准备环境与源码
Windows、像塑 9.7.2 或更高版本,先确认可以正常打开工程。
Node.js 24、PowerShell 7(
pwsh.exe)、Git,以及支持本地 stdio MCP 的客户端。独立的特效工程总目录,例如
D:/Effects;不要把源码目录当作特效工程目录。
在 PowerShell 7 中执行;已有源码则复用,历史版本按对应 tag 和 README 安装:
git clone https://github.com/sleepyquq/xiangsu-mcp.git
cd xiangsu-mcp
npm ci --ignore-scripts
npm test2. 安装像塑用户插件
$env:XIANGSU_EFFECT_WORKSPACE = 'D:/Effects'
# 仅在像塑不在默认安装位置时设置:
# $env:XIANGSU_EDITOR_ROOT = 'D:/Apps/Douyin AR'
node scripts/install.mjs安装器生成本机配置并安装 CodexXiangsuMCP@0.3.0。配置备份位于 .local/install-backups/。
先保存工作,再关闭并重新打开工程窗口,让插件生效。安装后不要移动源码仓库目录。
3. 注册 MCP 客户端
在支持 mcpServers JSON 的客户端中添加以下配置;使用仓库的实际绝对路径,合并而非覆盖已有服务:
{
"mcpServers": {
"xiangsu-editor": {
"command": "node",
"args": ["D:/Tools/xiangsu-mcp/src/server.mjs"]
}
}
}客户端找不到 node 时,用 Get-Command node 查询并填写 node.exe 的绝对路径。生成任务耗时较长,客户端支持时将工具超时设为 300 秒,然后重连 MCP。
4. 确认连接
打开允许目录内的测试工程,让 Agent 按适配说明核对工程路径,并读取当前场景。能正确读回场景,才说明已经连通编辑器。
让 Agent 开始工作
可以直接说:
使用 xiangsu-editor MCP,先读取适配说明,核对我打开的工程并读回场景。确认路径后再按我的要求修改。
工具参数、文件操作和 H5 制作流程由 Agent 按适配说明执行,无需手动拼写工具调用。
常见问题
情况 | 处理方式 |
| 0.3.0 要求像塑 9.7.2 起;升级像塑或选择历史 MCP,不绕过校验 |
| 高于本版验证基线,允许使用;在测试副本检查实际需要的功能 |
| 启动像塑并确认官方 MCP 服务可用、地址正确;原有本地编辑工具仍可使用 |
查不到原插件会话/ | 确认插件安装到当前像塑版本;保存工作、重跑安装器并重开工程 |
工程路径被拒绝 | 检查 |
工具列表仍是旧的 | 重连该 MCP 服务或重新加载客户端;仅新开对话可能不会重启服务进程 |
文字设置尺寸被拒绝 |
|
试玩无法开始 | 需要已挂载且能够运行的 Game2D 入口;依赖与临时代码恢复规则见适配说明 |
写入或生成超时/取消 | 操作可能已开始,先查状态或读回实际结果,不自动重复提交 |
更新像塑后,按实际版本重新运行安装器并在保存工作后重开工程;超出已测基线时只验证所需能力。停用时删除客户端的 xiangsu-editor 配置,并仅移除插件配置中的 CodexXiangsuMCP 条目,保留其他插件与回退备份。
测试与贡献
运行 npm test 验证协议、参数、路径边界、覆盖保护、转发、试玩隔离和恢复逻辑,不需要启动像塑。
真实回归只操作已确认可丢弃的测试副本。现有脚本会写入测试源码与素材并修改内存场景,不保存主场景:
node scripts/blank-setup.mjs 'D:/Effects/DisposableBlankTest'
node scripts/blank-check.mjs 'D:/Effects/DisposableBlankTest'
node scripts/blank-play.mjs 'D:/Effects/DisposableBlankTest'先在像塑打开该副本并核对会话。结束后关闭窗口并选择不保存;磁盘上的测试文件仍保留。请勿将正式工程用于这些脚本。
欢迎提交包含像塑版本、MCP 版本、客户端、复现步骤和脱敏日志的 Issue。修改接口或适配行为时,请区分自动测试与实际编辑器验证。
项目来源
这是非官方社区项目,不属于字节跳动、抖音或 TikTok。仓库包含独立编写的桥接、适配器、测试及用于互操作的接口元数据;不分发像塑可执行文件、官方运行库或素材包。所需官方资料与受管脚本从用户本机安装目录读取,第三方内容的权利归原权利人。
许可证
本项目自有代码采用 MIT 许可证,第三方内容遵循其原有许可。
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Build, edit and publish live 3D, AR and game scenes in ARClip from your AI assistant.
214 tools for AI agents over one MCP endpoint: image, video, audio, 3D, data, storage, mail, GPUs.
AI video, image and audio generation with 140+ AI models from any MCP agent
Build editable 3D scenes, direct characters and cameras, and export AI video references with MCP.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to control the Unity Editor through MCP, allowing scene building, runtime scripting, visual QA, and more.5Apache 2.0
- FlicenseNot gradedqualityAmaintenanceEnables AI agents to automate the PlayCanvas Editor and verify that scenes actually run, covering project, entity, script, asset, template, animation, scene, build, runtime, and VCS operations through a built-in MCP client.-
- FlicenseNot gradedqualityAmaintenanceEnables AI agents to automate the PlayCanvas Editor directly through its built-in MCP client, manipulating projects, entities, scripts, assets, scenes, builds and version control, then launching the app and inspecting runtime state and screenshots to confirm scenes actually run.-
- AlicenseNot gradedqualityAmaintenanceEnables AI agents to automate the PlayCanvas Editor directly through its built-in MCP client, covering projects, entities, scripts, assets, scenes, builds and version control. Agents can also launch the running app to capture screenshots, read logs, inspect live state and simulate input, verifying that scenes actually work.MIT