Photoshop Full MCP v2

Photoshop Full MCP v2 は、Photoshop 向けのローカル・機能ゲート付き MCP サーバーです。インストール済みの Photoshop 2026 (27.9) を対象としつつ、バージョンやインストールパスに依存しない設計です。

Windows 向けクイックスタート

前提条件: Windows 10/11、Photoshop 24 以降、Node.js 20 以降、Codex Desktop または Codex CLI。参照ホストは Photoshop 2026 (27.9) です。

1. 最新リリース から photoshop-full-mcp-v2.0.0-windows.zip とその .sha256 ファイルをダウンロードし、ZIP を展開します。

2. 展開した photoshop-full-mcp-2.0.0 フォルダーで PowerShell を開き、以下を実行します:

   powershell -NoProfile -ExecutionPolicy Bypass -File .\Install.ps1

   インストーラーはバンドルされたランタイムを検証し、%LOCALAPPDATA%\PS_MCP 配下にインストールして、独立した photoshop_full_mcp サーバーを登録します。チェックアウト/ダウンロードフォルダーは以後不要です。

3. 同梱の photoshop-full-mcp-v2.0.0.ccx をダブルクリックして Photoshop プラグインをインストールします。CCX インストールが利用できない場合は、Adobe UXP Developer Tools を使用し、Doctor が表示するインストール済みマニフェストを選択します。

4. Codex を再起動し、Photoshop を開いて、プラグイン > Photoshop Full MCP Bridge を選択します。

5. Codex で photoshop_pairing_begin を呼び出し、Photoshop パネルに 6 桁のコードを入力して、photoshop_host_describe を呼び出します。bridge.connected: true を含む応答が最初の成功確認です。

Doctor はいつでも実行できます:

powershell -NoProfile -ExecutionPolicy Bypass -File "$env:LOCALAPPDATA\PS_MCP\app\tools\Doctor.ps1"

デフォルトの承認モードは自動です。通常の編集コマンドに 1 件ずつの承認クリックは不要です。更新・削除・復旧手順については、図解入りの Windows インストールガイド と トラブルシューティングガイド を参照してください。

すべての Photoshop UI 機能がスクリプト化可能であるとは主張していません。カタログは以下に分類されます:

• supported: 対象ホスト上の実機 Photoshop フィクスチャで実装・検証済み

• experimental: 権限、モデル、ネットワーク、またはクレジットに依存

• requires_user: ユーザーが完了する必要がある明示的なネイティブメニュー手順を含む非ブロッキングジョブを作成します。OS クリックは自動化しません

• unverified: インベントリ登録済みだが、ローカルフィクスチャが合格するまでブロック

• unavailable: 信頼できるデスクトップ UXP コントラクトが不明

Related MCP server: Photoshop MCP Server

アーキテクチャ

• MCP サーバー: stdio 上の Node.js/TypeScript

• Photoshop ブリッジ: 認証付き 127.0.0.1 上の UXP Manifest v5 パネル

• ディスカバリー: ポート 38452 から 38462

• ペアリング: photoshop_pairing_begin が開く信頼済みローカル Windows ダイアログにのみ表示される 6 桁のコード

• 実行: スキーマ検証、機能/リスクポリシー、FIFO キュー、executeAsModal、1 つの履歴グループ化、実行前後の状態検証

• 承認: デフォルトで自動。スコープ限定のワンタイムトークン、リプレイ保護、パス制限、高度なディスクリプタ許可リストは引き続き適用

• デフォルトのファイルブリッジ: エクスポートと制限付き再オープンは、ピッカーなしでサーバー所有の %LOCALAPPDATA%\PS_MCP\exports フォルダーを使用。ユーザー選択による永続的な UXP フォルダーはオプションとして残ります

• 高度な生 batchPlay: デフォルトでは非表示。PS_MCP_ADVANCED=confirm を設定すると、引数なしの deselect と invert ディスクリプタのみが公開されます。その他の生ディスクリプタとすべての生 JSX は、Photoshop に到達する前に拒否されます

• テレメトリ: なし

広範な機能インベントリは catalog/features.json にあります。実行可能なコントラクトは catalog/commands.json にあります。

現在の監査済み状態: 101 のコマンドコントラクト (87 supported、1 experimental、0 unverified、11 requires_user、2 unavailable) と 52 の機能グループ (21 supported、1 experimental、0 unverified、10 requires_user、20 unavailable)。コマンドまたは機能グループが supported に昇格するのは、署名付きの実機 Photoshop 27.9 フィクスチャが合格した場合のみです。無効な継承 Generative Fill および Neural Filter ディスクリプタは明示的に利用不可となり、不正な形式または許可リスト外の生ディスクリプタはサーバー側で拒否されるため、Photoshop の不明コマンドダイアログが開くことはありません。

ソースからのインストール

上記のリリース ZIP インストールを推奨します。コントリビューターは代わりにリポジトリをクローンして以下を実行できます:

npm ci --no-audit --no-fund
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\Install-Local.ps1

互換性ラッパーは一度ビルドし、自己完結型の本番ランタイムを %LOCALAPPDATA%\PS_MCP にコピーして、そのインストール済みコピーを登録します。その後のソースチェックアウトの移動や削除は MCP サーバーに影響しません。インストーラーは既存の photoshop_mcp と並んで photoshop_full_mcp を登録します。古いパッケージの削除や編集は行いません。

UXP プラグインについては、npm run uxp:package を実行して生成された CCX をインストールするか、Doctor が報告するインストール済みマニフェストを Adobe UXP Developer Tools で読み込みます。パネルでエクスポートフォルダーを選択することもできます。選択しない場合、document.export は認証済みのサーバー所有デフォルトエクスポートフォルダーを使用します。

更新とアンインストール

# Download, verify, and install the newest GitHub release
powershell -NoProfile -ExecutionPolicy Bypass -File "$env:LOCALAPPDATA\PS_MCP\app\tools\Update.ps1"

# Remove the installed runtime and Codex registration; preserve pairing and exports
powershell -NoProfile -ExecutionPolicy Bypass -File "$env:LOCALAPPDATA\PS_MCP\app\tools\Uninstall.ps1"

# Also remove pairing state and exports
powershell -NoProfile -ExecutionPolicy Bypass -File "$env:LOCALAPPDATA\PS_MCP\app\tools\Uninstall.ps1" -RemoveUserData

安全な使用手順

1. photoshop_host_describe

2. photoshop_capability_list

3. photoshop_state_get

4. photoshop_command_search / photoshop_command_describe

5. photoshop_command_execute

6. 視覚的な変更後の photoshop_preview_get

破壊的、検証、クレジット消費、および許可リスト登録済みの高度なコマンドはローカルサーバーによって自動承認されるため、Photoshop パネルでの承認クリックは不要です。photoshop_approval_request は互換性 API として残り、完了済みのスコープ限定ジョブを即座に返します。PS_MCP_APPROVAL_MODE=panel は、以前のクリック承認ワークフローを意図的に希望する場合のみ設定してください。パスサンドボックス、機能ステータスゲート、リプレイ保護、生ディスクリプタ許可リストはバイパスされません。

ローカルホスト検証の場合は、PS_MCP_VALIDATION=confirm を指定して一時サーバーを起動します。これにより photoshop_validation_request と photoshop_command_validate が公開されます。これらはカタログ登録済みの未検証 UXP DOM コマンドのみを受け入れ、デフォルトで自動承認され、PS_MCP_VALIDATION_* という名前のドキュメントのみを操作します。検証実行によって機能が自動的に昇格することはありません。

インベントリと実機エビデンス監査

npm run check には、すべてのコマンドと機能エントリの機械監査が含まれます。監査では、ハンドラーの存在、実機フィクスチャの来歴、カタログコントラクトのダイジェストずれ、ステータス/エンジン/ルートの整合性が報告されます。supported コマンドまたは機能は、evidence/live 配下に対応するトランザクション拘束型フィクスチャが存在しない限りチェックに失敗するため、実装やドキュメント文字列だけではサポートを昇格できません。

完全な読み取り専用レポートは以下で生成します:

npm run audit:inventory:json

昇格レビューにはさらに、ブリッジが現在接続されている新しく取得した photoshop_host_describe 結果が必要です。実機フィクスチャ自体にも有効なローカルエビデンス署名が必要です:

npm run audit:promotion -- --promotion-command selection.ellipse --host-report .\host-describe.json

UXP ブリッジが稼働していない場合、古いフィクスチャが存在してもコマンドは LIVE_HOST_DISCONNECTED で失敗します。エビデンスは、呼び出し元が作成したホスト、結果、またはアサーション JSON からは受け付けられなくなりました。レコーダーは検証プロファイルの MCP セッションを自ら起動し、接続された Photoshop の ID を検証し、自動スコープ限定承認を受け取り、PS_MCP_VALIDATION_* ドキュメントでコマンドを実行し、状態とピクセルプレビューのハッシュをチェックし、必要な場合は元に戻すラウンドトリップを実行し、一時ドキュメントを閉じて、トランザクション領収書に署名します:

Set-Content .\validation-args.json '{"left":0,"top":0,"right":64,"bottom":64}'
npm run evidence:record -- --command selection.ellipse --args .\validation-args.json

プライベートなエビデンス署名キーは、ユーザーのみの ACL で %LOCALAPPDATA%\PS_MCP 配下に保存されます。リポジトリには公開検証キーのみが保存されます。レコーダーはハッシュと許可リスト登録済みのホスト/検証メタデータのみを書き込みます。ピクセル、ドキュメントの内容や名前、プロンプト、ブリッジトークン、リクエスト引数、生の Photoshop 結果はコピーしません。エビデンスの記録は catalog/commands.json を編集しません。ステータス昇格は別途レビューされた変更として残ります。

検証

npm run check
npm test
npm --prefix apps\uxp-plugin run check
npm run build
npm run test:contract

実機生成テストは意図的に除外されています。クレジットを消費し、サインイン済みの Adobe アカウントに依存する可能性があるため、明示的な承認が必要です。

検証実行が中断された場合は、クリーンアップ前にアクティブドキュメントを検査してください。メンテナンスコマンドはデフォルトでドライランであり、アクティブタイトルが所有する PS_MCP_* 検証タイトルでなくなるとすぐに停止します:

npm run cleanup:owned-documents
npm run cleanup:owned-documents -- --apply

記録済み ActionJSON の追加

Photoshop の開発者向け Action Recorder でコマンドをキャプチャし、未検証のカタログエントリを生成します:

node .\scripts\import-action-recording.mjs --id filters.example --category filter --en "Example Filter" --ko "예제 필터" --file .\recording.json

インポーターはカタログ定義と SHA-256 エビデンスダイジェストを出力します。コマンドを supported に昇格させることはありません。昇格には分離ドキュメント統合フィクスチャが必要です。

データの場所

• ペアリングシークレットとエンドポイントメタデータ: %LOCALAPPDATA%\PS_MCP

• デフォルトのエクスポート: %LOCALAPPDATA%\PS_MCP\exports

• UXP トークン: Photoshop UXP セキュアストレージ

シークレットとプレビュー画像データがログに書き込まれることはありません。