トラブルシューティング

よくあるつまずき(接続、スクリプト、Web UI の認証)を解決します。まず下のクイックチェックから始めてください。

まずクイックチェック
  • Photoshop がインストールされ、開いていること — サーバーは起動できますが、開いているインスタンスがあれば原因の半分を除外できます。
  • MCP クライアントの設定が正しいサーバーを指していること — 「はじめかた」のスニペットと比較してください。
  • Web UI のタブ: CLI が表示した正確な URL から再読み込みしてください — サーバー再起動をまたいで開いたままのタブは古いトークンを持っています。

よくある問題

「Photoshop が見つかりません」

原因: Photoshop が既定のインストール場所にないため、サーバーがバイナリを見つけられません。

解決策:

  • Photoshop が既定の場所にインストールされていることを確認するか、クライアント設定の PHOTOSHOP_PATH でカスタムパスを指定してください:
mcp config
{
  "env": {
    "PHOTOSHOP_PATH": "C:\\Custom\\Path\\Adobe Photoshop 2025\\Photoshop.exe"
  }
}

「Photoshop に接続できませんでした」

原因: Photoshop が起動していないか、スクリプト実行がブロックされています。

解決策:

  • Photoshop が起動していることを確認してください — サーバーは起動を試みますが、すでに起動しているインスタンスの方が速く確実に接続できます。
  • Photoshop の環境設定でスクリプト実行が有効になっていることを確認してください。
  • Windows では、セキュリティ設定で COM オートメーションがブロックされていないことを確認してください。

Web UI: /api/* からの 401 unauthorized

原因: すべての /api/* リクエストは、UI サーバー起動時に生成されるセッショントークンを提示する必要があります。ブラウザは自動で取得しますが、古いタブや外部スクリプトは取得しません。

解決策:

  • ブラウザの場合: photoshop-mcp-ui が表示した URL からページを再読み込みしてください。
  • スクリプトの場合: ~/.photoshop-mcp/ui-session.json からトークンを読み取り、ヘッダーとして送信してください:
terminal
TOKEN=$(node -p "require('$HOME/.photoshop-mcp/ui-session.json').token")
curl -H "x-psmcp-token: $TOKEN" http://127.0.0.1:5174/api/status

Authorization: Bearer <token> でも構いません。サーバー起動前に PSMCP_UI_TOKEN を設定すると既知のトークンを固定できます。

Web UI: 403 invalid_host または invalid_origin

原因: トークンチェックの前に 2 つのガードが実行されます。invalid_host は Host ヘッダーがサーバーのポート上のループバックアドレスに解決されなかったことを意味します(DNS リバインディングをブロック)。invalid_origin はリクエストが UI 自身とは異なるオリジンから来たことを意味します。

解決策:

  • CLI が表示した正確な URL(http://127.0.0.1:<port>)から UI を開いてください — 単にマシンを指すホスト名ではなく、別のポートで配信されたページからでもありません。

photoshop_execute_script が「Result: undefined」を返す

原因: ExtendScript はサーバー側の IIFE ラッパー内で実行されます。明示的な return がないと、ブロックは undefined と評価されます — 副作用(レイヤー名の変更、プロパティの変更)は適用されている場合があります。

解決策:

  • スクリプトに明示的な return を追加してください:
photoshop_execute_script
photoshop_execute_script({
  code: `
    app.activeDocument.activeLayer.name = "Updated";
    return { ok: true };
  `
})

詳しくは「ツールカタログ」の photoshop_execute_script セクションをご覧ください。

「Script execution timeout」

原因: 既定のタイムアウトは 30 秒で、大きなドキュメントでは処理がこれを超えることがあります。

解決策:

  • 複雑な操作は小さなステップに分割し、順番に実行してください。

Web UI: CLI アカウント認証

Web UI で Claude Code / Gemini CLI のアカウントモードを使う場合の症状。

症状考えられる原因解決策
cli_not_foundClaude Code / Gemini CLI がインストールされていないnpm i -g @anthropic-ai/claude-code または npm i -g @google/gemini-cli
not_authenticatedCLI の OAuth セッションがない(API キー / SDK 認証はカウントされません)ターミナルで claude auth login または gemini auth login を実行するか、API キー認証に切り替える
SDK クライアントは動くが UI の CLI モードが失敗するSDK / API の資格情報は CLI の OAuth とは別Web UI では API キーを使うか、CLI モード用に claude auth login でログインする
claude / gemini が PATH にないカスタムのインストール場所Settings → CLI path → Check connection
IDE ではチャットできるが UI ではできない(CLI モード)OAuth トークンは CLI 専用UI では CLI アカウントを使用 — API キーと CLI セッションは別です
Gemini の複数ターンが内容を忘れるように感じるヘッドレス CLI はターンごとに新しいセッションを開始する場合がある既知の制限。履歴はプロンプトの先頭に付加されます(MVP)

デバッグログ

クライアント設定で LOG_LEVEL=0 を指定すると詳細なログが有効になります:

mcp config
{
  "env": {
    "LOG_LEVEL": "0"
  }
}

まだ解決しませんか?

既存の issue を検索するか、新しく作成してください — デバッグログで取得したログがあると非常に助かります。