00:00 / 00:00

Persona

MCPサーバー

@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_TOKENPersonaで生成したAPIキートークン（必須）
PERSONA_ADDRESS接続先端末のアドレス。空欄時はローカルホストの127.0.0.1:25034。ホスト、ホスト:ポート、または完全なws:// URLを指定可能

多くのMCPクライアントはPersonaの起動前にサーバープロセスを立ち上げるため、サーバーは初回のツール呼び出しが来るまでWebSocket接続を保留します。トークン未設定、Persona未起動、またはキー失効時はプロセスを落とさず、原因と対処を示す診断エラーをアシスタントに返します。

接続されると、Personaの接続中のクライアント一覧にPersona MCP（クライアント識別子付き、開発者：LAPLACE）が表示されます。

ツール一覧

ツールは生のプロトコルメソッドをそのまま並べるのではなく、よく使うタスク単位（約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シーン名の変更、またはシーンと含まれるアイテムの削除（最後の1つは削除不可）
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指定したオートメーションのアクションまたはトリガー種別の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アイテムはメートルとラジアンを使います。座標系と単位は各ツールのスキーマ説明に記載されています。

バージョン関連のツールにはmodel-history機能が必要です。モデルのバージョン履歴はユーザーがデスクトップアプリ側でオンにする必要があり、MCPツールが自動的にオンにすることはありません。オフの間はsave_versionがinvalid-stateを返します。ツールの説明では、モデルのバインディング・ショートカット・表情を編集する前に、これから行う変更内容を名前に付けてsave_versionを呼ぶようアシスタントに案内しており、あとから比較や復元ができるようになっています。switch_versionにはdestructiveHintが付いています。切り替えによって未保存の変更が上書きされる場合はエラーになり、先にバックアップバージョンとして保存するか（unsavedChanges: 'save'）、破棄するか（'discard'）をアシスタントがユーザーに確認します。

ステージの視覚的検証

capture_stageは下位のstage.captureメソッドを使い、現在のステージウィンドウを透過PNG画像としてキャプチャします。長辺の既定値は1024ピクセル（最大2048ピクセル）で、拡大補間は行いません。この機能にはデスクトップアプリ側のstage-capture機能が必要です（Persona 0.55.0以降で対応。古いバージョンでは更新を促すメッセージが返されます）。

1回のキャプチャにつき1フレーム分の描画時間がかかるため、定期的なポーリングではなく、変更後の確認に必要なときだけ呼び出してください。

汎用呼び出し：call_api

専用ツールが用意されていない機能（カメラ制御、ライティング、環境設定、レイヤーエフェクト、3DプロップやWebレイヤー、トラッキングソース設定、リップシンク、音声、全体設定など）は、call_apiツールから直接呼び出せます。メソッド名とパラメータオブジェクトを渡すだけで実行でき、未知のメソッド名もそのまま転送されるため、MCPパッケージの更新を待たずにPersona本体の新しいAPIメソッドを利用できます。

不正なパラメータを渡した場合は該当フィールドを示すエラーが返り、プロトコルエラー時には有効な値を取得するためのツールがヒントとして案内されます。

最終更新日：2026年11月3日

プラグインAPISDK
Tech otakus destroy the world