@laplace.live/persona-mcp 是 Persona 官方的 MCP（Model Context Protocol）服务器，将 插件 API 封装为标准工具集供 AI 助手调用：切换场景、加载与摆放模型、控制表情与动作、执行自动化流程，以及截取舞台画面来核对修改结果。
该服务与 Web 控制台 及 Stream Deck 插件 基于相同的底层 API 构建，遵循相同的鉴权与权限模型，不会绕过桌面应用的任何安全限制。
前提条件
| 项目 | 要求 |
|---|---|
| MCP 客户端 | Claude Desktop、Claude Code、Cursor、Codex 等支持 MCP 协议的客户端 |
| Node.js | 24 或更高版本（供 npx 运行服务包） |
| LAPLACE Persona | 运行中，且已开启 插件 API |
| API Key | 在 设置 → 插件 API 中生成并获取，配置为客户端的 PERSONA_TOKEN |
配置指南
在 MCP 客户端的配置文件中添加服务定义。Claude Desktop 的 claude_desktop_config.json 与 Cursor 的 mcp.json 均采用如下格式：
{
"mcpServers": {
"persona": {
"command": "npx",
"args": ["-y", "@laplace.live/persona-mcp"],
"env": { "PERSONA_TOKEN": "sk-lp-v1-…" }
}
}
}在 Claude Code 中可通过命令行一键添加：
claude mcp add persona -e PERSONA_TOKEN=sk-lp-v1-… -- npx -y @laplace.live/persona-mcp环境变量
| 变量 | 说明 |
|---|---|
PERSONA_TOKEN | 在 Persona 中生成的 API Key 凭证。必填项 |
PERSONA_ADDRESS | 目标实例地址。留空默认为本机 127.0.0.1:25034；支持输入 主机、主机:端口 或完整的 ws:// URL |
由于大多数 MCP 客户端会在 Persona 启动前先启动服务进程，MCP 服务器采用按需连接方式，直到首次收到工具调用时才建立 WebSocket 连接。若未配置 Token、Persona 未启动或密钥已失效，服务器会返回结构化的诊断错误，引导助手排查问题，而不会直接退出进程。
建立连接后，Persona 的 已连接的客户端 列表中会显示 Persona MCP（附带客户端标识，开发者：LAPLACE）。
API Token 具备完整的控制权限。持有该 Token 的 AI 助手可切换场景、增删模型、修改舞台布局并截取舞台画面。除非开启了允许局域网访问，否则服务仅监听本机回环地址。
工具列表
工具集按常用任务组织（近 30 个），而非逐一照搬底层协议方法，既降低了助手的选择难度，也节省上下文开销。所有只读操作均标有 readOnlyHint；破坏性操作（delete_scene、remove_item、delete_automation 与 switch_version）带有 destructiveHint 标识，可在支持的客户端中触发确认提示。
| 工具 | 功能说明 |
|---|---|
get_state | 查询应用版本与能力集、所有场景列表，以及当前场景各图层的 ID、格式、可见性、坐标与加载错误信息（loadError）；本机连接且具备 asset-import 时还会返回已配置的 pluginFolders |
capture_stage | 截取当前舞台画面并以图片形式返回，供支持视觉的助手检查执行结果 |
activate_scene create_scene | 切换至指定场景；创建新场景并立即激活 |
rename_scene delete_scene | 重命名指定场景；删除场景及其包含的图层（最后一个场景不可删除） |
list_models add_model | 列出可用模型；向舞台添加新模型，或直接替换现有图层 |
import_asset | 将本机模型或素材文件登记到 素材库（调用 asset.import，需 asset-import 能力；位于已配置插件目录外的文件会在桌面端弹出确认提示） |
describe_model | 查询单个图层项的详细信息：位置、能力、可用表情与动作列表，以及当前播放状态 |
remove_item set_visible | 从当前场景中移除图层项；或仅切换其显示/隐藏状态 |
set_placement reset_placement | 调整图层的位置、缩放与旋转；或重置为默认值。仅更新传入的字段，不支持的字段会被忽略并返回提示 |
set_text | 更新指定文本图层的文本内容；设置 transient: true 可在不写入场景且不产生撤销记录的情况下临时显示文本，传入 text: null 可清除临时文本并恢复保存内容 |
set_expression | 按名称启用或禁用表情；已处于目标状态时不会重复触发 |
play_motion stop_motion | 按动作组与索引播放指定动作；或淡出当前动作并回到待机状态 |
list_automations get_automation | 列出 自动化 流程及各模型的快捷键；或读取单条自动化的完整时间线、操作与触发条件（需 automation-editing 能力） |
save_automation delete_automation | 新建或整体更新一条自动化的时间线定义（新建自动化默认处于禁用状态且不绑定快捷键）；或删除指定自动化（需 automation-editing 能力） |
describe_automation_kind | 查询指定自动化操作（action）或触发条件（trigger）类型的 JSON Schema（不传参数时列出全部可用类型），无需请求 Persona |
run_automation control_automation | 按 ID 从头执行已启用的自动化；或驱动自动化时间线走带（play、pause、stop、prepare、seek）并返回当前运行状态（需 automation-transport 能力） |
trigger_hotkey | 触发舞台上指定模型的 快捷键 |
list_versions save_version | 列出模型的 已保存版本 及当前未保存的文件；将模型文件保存为一个版本，可附带名称与备注 |
switch_version | 将模型文件还原为某个已保存版本并重新载入模型 |
call_api | 通用调用入口：直接调用任意底层插件 API 方法，参数原样转发 |
2D 图层的位置以舞台中心为原点，采用像素单位（+y 轴向下），旋转以弧度表示；3D 图层采用米和弧度。所有坐标规范均在各工具的 Schema 说明中写明，便于模型换算数值。
版本工具依赖 model-history 能力。模型的版本历史需由用户在桌面端主动开启，MCP 工具不会自动开启；未开启时 save_version 返回 invalid-state。工具说明会引导助手在修改模型的绑定、快捷键或表情之前先调用 save_version 并注明即将进行的操作，方便事后对比与回退。switch_version 标有 destructiveHint：若切换会覆盖未保存的修改，工具会返回错误，由助手询问用户是先保存为备份版本（unsavedChanges: 'save'）还是直接丢弃（'discard'）。
舞台视觉校验
capture_stage 工具基于底层的 stage.capture 方法实现，将当前舞台窗口截取为带透明通道的 PNG 图像，最长边默认 1024 像素（最大 2048 像素），不会放大低分辨率画面。该功能需要桌面端支持 stage-capture 能力（0.55.0 及以上版本提供；旧版本会提示升级应用）。
每次截图都会占用舞台一帧的渲染时间，建议仅在需要核对画面时调用，不要高频轮询。
通用调用：call_api
专用工具尚未覆盖的功能（如相机控制、灯光、环境、图层 特效、3D 道具与网页图层、捕捉源配置、口型同步、语音以及全局设置），均可通过 call_api 工具直接调用，传入目标方法名和参数对象即可。call_api 会直接转发未知方法名，因此 Persona 新增的 API 方法无需等待 MCP 服务包更新即可调用。
若传入参数校验失败，错误响应会指明出错字段；若发生协议错误，响应中还会附带提示，说明可调用哪个前置工具获取有效参数。
最后更新于 2026年11月3日