@laplace.live/persona-mcp 是 Persona 官方的 MCP 伺服器，把 外掛 API 交給 AI 助理：切換場景、載入與擺放模型、開關表情、播放動作、執行自動化，以及擷取舞台畫面來確認改動的效果
它和 Web 控制台、Stream Deck 外掛 走的是同一套 API，沒有額外開放任何東西。它自己不碰桌面應用程式的程式碼，能做的事外掛 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": "psk_…" }
}
}
}Claude Code 用一條命令就行：
claude mcp add persona -e PERSONA_TOKEN=psk_… -- npx -y @laplace.live/persona-mcp兩個環境變數：
| 變數 | 填什麼 |
|---|---|
PERSONA_TOKEN | 你在 Persona 裡建立的那把金鑰的權杖。必填 |
PERSONA_ADDRESS | 留空即本機的 127.0.0.1:25034。也接受 主機、主機:連接埠，或一整條 ws:// URL |
啟動時它不會失敗：MCP 用戶端往往在 Persona 打開之前就把伺服器拉起來了，所以它直到第一次工具呼叫才去連線。權杖沒填、應用程式沒開或者金鑰已經撤銷，都會變成一段告訴助理該改什麼的文字，而不是一聲當掉
連上之後，Persona 的 已連線的用戶端 裡會出現一列 Persona MCP，括號裡是用戶端自報的名字，開發者是 LAPLACE
權杖等同於密碼。拿到它的助理可以切換場景、載入模型、改動舞台，還能看見舞台畫面。伺服器預設只監聽本機回送位址，除非你打開了允許區域網路存取
工具
工具是按任務劃分的，一共二十來個，而不是給每個協定方法都包一層——清單太長反而會讓模型選不準，每輪對話也更耗上下文。所有唯讀工具都帶 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_expression | 按名字開關一個表情。已經是這個狀態就什麼都不做 |
play_motion stop_motion | 按分組和序號播放一段動作；淡出目前的動作，讓待機動畫接回來 |
list_automations run_automation | 列出 自動化 和目前模型的快速鍵；按 id 執行一條自動化 |
trigger_hotkey | 觸發目前模型的某個 快速鍵 |
call_api | 直接呼叫外掛 API 的任意方法，參數原樣轉發 |
2D 項目的位置是以舞台中心為原點的像素（+y 向下），旋轉用弧度；3D 項目用公尺和弧度。這些約定都寫在工具說明裡，助理不必猜
查看舞台
capture_stage 背後是新的 stage.capture 方法：把舞台視窗目前的樣子擷取成一張帶透明通道的 PNG，最長邊預設 1024 像素，最大 2048，且從不放大。它需要應用程式回報 stage-capture 能力——0.55.0 起提供，更早的版本會直接告訴助理去更新
每擷取一張，舞台都要停下一幀，所以它只該在需要確認結果時呼叫，而不是拿來輪詢
兜底的 call_api
其餘工具沒涵蓋到的——相機、燈光、環境、圖層 特效、物件與網頁、生成道具、追蹤來源、口型同步、語音、設定——都從 call_api 走：給它方法名稱和參數物件即可。它不認識的方法名稱也照樣轉發，所以更新了 Persona 之後，新方法不必等這個套件跟進就能用
參數不對時，回傳的錯誤會說明是哪個欄位；協定層面的錯誤還會附上一句提示，告訴助理正確的值該從哪個工具拿
最後更新於 2026年9月20日