@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 金鑰 | 在 設定 → 外掛 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日