@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 用戶端會在宿主應用程式啟動前拉起服務程序，MCP 伺服器直到首次接收到工具呼叫時才會建立 WebSocket 連線。若未設定 Token、Persona 未啟動或金鑰已失效，伺服器將回傳格式化的診斷錯誤提示，引導模型定位問題，而非直接異常結束。
建立連線後，Persona 用戶端的 已連線的用戶端 清單中將顯示 Persona MCP（附帶用戶端宣告的應用程式識別碼，開發者：LAPLACE）。
API Token 具備完整的控制權限。持有該 Token 的 AI 助理可切換場景、增刪模型、修改舞台排版並擷取舞台畫面。MCP 伺服器預設僅監聽本機回送位址，除非明確開啟了允許區域網路存取。
工具清單
工具集依高頻任務情境劃分（共 20 餘個），而非機械映射底層協定的所有細節，從而降低模型的決策複雜度並節省上下文視窗。所有唯讀操作均標記有 readOnlyHint；破壞性操作（如 delete_scene 與 remove_item）帶有 destructiveHint 標識，可在支援的用戶端中觸發二次確認。
| 工具 | 功能說明 |
|---|---|
get_state | 查詢應用程式版本與功能集、所有場景清單，以及目前場景各圖層的 ID、格式、可見性與座標；通常作為多步驟操作的首選前置呼叫 |
capture_stage | 擷取目前舞台畫面並以圖片形式回傳，供具備多模態能力的助理直觀檢查執行結果 |
activate_scene create_scene | 切換至指定場景；建立新場景並立即啟用 |
rename_scene delete_scene | 重新命名指定場景；刪除場景及其包含的圖層物件（最後一個場景不可刪除） |
list_models add_model | 列出可用模型清單；向舞台新增模型，或就地替換現有圖層 |
describe_model | 查詢單一圖層項目的詳細資訊：位置、功能、可用表情與動作清單，以及目前播放狀態 |
remove_item set_visible | 從目前場景中移除圖層項目；或僅切換其顯示/隱藏狀態 |
set_placement reset_placement | 調整圖層的位置、縮放與旋轉；或重設為預設值。僅更新明確傳入的欄位，不支援的欄位將被忽略並回報提示 |
set_text | 更新指定文字圖層的文字內容；設定 transient: true 可在不寫入場景且不產生復原記錄的情況下呈現動態文字，傳入 text: null 可清除暫態文字恢復已儲存內容 |
set_expression | 依名稱啟用或停用表情；若狀態未變更則保持等冪 |
play_motion stop_motion | 依動作群組與索引播放指定動作；或淡出目前動作並恢復預設待命狀態 |
list_automations run_automation | 列出 自動化 工作流程及各模型的快速鍵；依 ID 觸發執行自動化 |
trigger_hotkey | 觸發舞台上指定模型的 快速鍵 |
call_api | 通用呼叫介面：支援直接呼叫任意底層外掛 API 方法，參數原樣轉發 |
2D 圖層的位置以舞台中心為原點，採用像素單位（+y 軸向下），旋轉以弧度表示；3D 圖層採用公尺與弧度。所有座標規範均已在各工具的 Schema 說明中詳細宣告，便於模型準確推導數值。
舞台視覺校驗
capture_stage 工具基於底層的 stage.capture 方法實作：將目前舞台算繪視窗擷取為帶有透明色版的 PNG 影像，最長邊預設 1024 像素，最大 2048 像素，且絕不進行插值放大。該功能需要應用程式回報 stage-capture 功能支援（自 0.55.0 版本起提供；若版本過舊，工具將提示更新應用程式）。
每次畫面擷取操作會消耗舞台單訊框算繪時間，因此應僅在需要視覺驗證時呼叫，不應作為高頻輪詢手段。
通用呼叫：call_api
針對專用工具尚未涵蓋的功能模組——如相機控制、燈光、環境、圖層 特效、3D 道具與網頁圖層、動態追蹤來源設定、口型同步、語音以及全域設定等——均可透過 call_api 工具直接呼叫：傳入目標方法名稱與參數物件即可。call_api 具備透明轉發機制，即使 Persona 用戶端更新了新協定方法，無需等待 MCP 伺服器發布新版即可直接呼叫。
若傳入參數驗證失敗，錯誤回應將指出具體錯誤欄位；若發生協定層級錯誤，回應中亦會附帶修復建議與上下文指引，告知模型取得有效參數的前置工具。
最後更新於 2026年10月11日