MCPサーバー ✽ Persona ✽ LAPLACE

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

サーバープロセスは遅延接続アーキテクチャを採用しています。多くのMCPクライアントはホストアプリの起動前にサーバープロセスを立ち上げるため、初回のツール呼び出しが発生するまでWebSocket接続を保留します。トークン未設定、Persona未起動、あるいはキー失効時はプロセスが異常終了することなく、問題を解決するための診断メッセージがアシスタントに返されます。

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

APIトークンはパスワードと同等の権限を持ちます。トークンを保持するAIアシスタントはシーンの切り替え、モデルの配置変更、ステージ操作、画面キャプチャの取得が可能です。ローカルネットワークからのアクセスを許可を明示的に有効にしない限り、サーバーはループバックアドレスのみを受け付けます。

ツールは生のプロトコルメソッドを機械的に網羅するのではなく、利用頻度の高いタスク単位（約20個）で体系化されており、モデルの選択ミスを防ぎコンテキスト消費を抑えています。すべての読み取り専用ツールにはreadOnlyHintが付与され、破壊的変更を伴うツール（delete_sceneやremove_item）にはdestructiveHintが指定されているため、対応クライアントで実行確認ダイアログが表示されます。

ツール名	説明
`get_state`	アプリバージョン、機能セット、全シーン一覧、およびアクティブシーン内アイテムのID・形式・表示状態・座標を取得（初期調査に推奨）
`capture_stage`	ステージの現在状態を画像としてキャプチャし、マルチモーダルモデルによる視覚的な結果確認を可能にする
`activate_scene` `create_scene`	指定シーンへの切り替え、または新規空シーンの作成と切り替えを実行
`rename_scene` `delete_scene`	シーン名の変更、またはシーンと内包アイテムの削除（最後の1つは削除不可）
`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アイテムはメートル単位とラジアンを使用します。これらは各ツールのスキーマ説明に定義されています。

ステージの視覚的検証

capture_stageは下位のstage.captureメソッドを使用し、ステージのレンダリング結果をアルファチャンネル付きPNG画像として取得します。長辺はデフォルトで1024 px（最大2048 px）で、アップスケールは行われません。本機能にはアプリ側のstage-capture機能対応が必要です（Persona 0.55.0以降で利用可能。古いバージョンでは更新案内が返されます）。

1回のキャプチャにつき1フレーム分のレンダリング処理を要するため、ポーリング監視ではなく必要なタイミングでの検証呼び出しに適しています。

汎用呼び出し：call_api

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

不正なパラメータを指定した場合は対象フィールドを示すエラーが返され、プロトコルエラー時には正しい値を取得するための推奨ツールがヒントとして提示されます。

MCPサーバーはプロトコル変換を行うブリッジとして機能し、ツールの呼び出しをプラグインAPIリクエストに変換します。各メソッドの仕様や引数の詳細は、プラグインAPIおよびSDKリファレンスを参照してください。

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

プラグインAPI SDK

Persona