Photoshop MCP Server

Photoshop MCP 服务

这是一个使用模型上下文协议（MCP）服务在 macOS 和 Windows 上远程控制 Photoshop 的项目。

概述

本项目使用 FastAPI 实现 MCP 服务，并通过以下方式控制 Photoshop：

macOS

1. AppleScript 后端——适用于所有 Photoshop 版本
2. UXP Plug-in 后端——适用于 Photoshop CC 2021 及以上版本（WebSocket 通信）

Windows

1. PowerShell 后端——适用于所有 Photoshop 版本
2. UXP Plug-in 后端——适用于 Photoshop CC 2021 及以上版本（WebSocket 通信）

功能

• 使用 FastAPI/Starlette 实现 REST/WebSocket 端点
• 跨平台支持（macOS/Windows）
• 通过 AppleScript/PowerShell 后端控制 Photoshop
• 通过 UXP Plug-in 后端控制 Photoshop（WebSocket 通信）
• 插件打包功能
• 缩略图生成能力（支持 WebSocket 流式传输）
• 通过 Cluster 模式管理多个 Photoshop 实例
• LLM 自动修图功能

系统要求

• Python 3.11 及以上版本
• macOS 或 Windows 10/11
• Adobe Photoshop 2023 及以上版本

安装

pip install photoshop-mcp-server

或者从源码安装：

git clone https://github.com/StarBoze/photoshop-mcp-server.git
cd photoshop-mcp-server
pip install -e .

详细安装步骤请参阅安装指南。

环境配置详情

创建和管理虚拟环境

使用 Python 虚拟环境可以避免依赖冲突：

# 仮想環境の作成
python -m venv venv

# 仮想環境の有効化（macOS/Linux）
source venv/bin/activate

# 仮想環境の有効化（Windows）
venv\Scripts\activate

# 依存パッケージのインストール
pip install -e .

依赖包

主要依赖包：

• FastAPI：用于实现 REST 和 WebSocket 端点
• Uvicorn：ASGI 服务
• Pydantic：数据验证
• Starlette：WebSocket 支持
• psutil：进程管理（Cluster 模式）
• grpcio：gRPC 通信（Cluster 模式）
• litellm：LLM 集成（自动修图功能）

运行模式

服务可按以下模式运行：

• 普通模式：photoshop-mcp-server start

  • 在后台启动服务

• 前台模式：photoshop-mcp-server start --foreground

  • 运行时在终端显示日志
  • 适用于调试

• 调试模式：photoshop-mcp-server start --debug

  • 显示详细日志
  • 同时显示请求和响应的内容

• UXP 模式：photoshop-mcp-server start --bridge-mode uxp

  • 使用 UXP 插件控制 Photoshop

使用方法

基本用法

# サーバーを起動（プラットフォームに応じたデフォルトバックエンド）
photoshop-mcp-server start

# ヘルプを表示
photoshop-mcp-server --help

指定平台专用后端

# macOSでAppleScriptバックエンドを使用
photoshop-mcp-server start --bridge-mode applescript

# WindowsでPowerShellバックエンドを使用
photoshop-mcp-server start --bridge-mode powershell

# UXPバックエンドを使用（クロスプラットフォーム）
photoshop-mcp-server start --bridge-mode uxp

详细用法请参阅文档。

使用 UXP 后端

使用 UXP 后端需要执行以下步骤：

1. 打包 UXP 插件

photoshop-mcp-server package_plugin

2. 显示 UXP 插件的安装步骤

photoshop-mcp-server install_plugin

3. 按照显示的步骤安装插件

4. 启用 UXP 后端并启动服务

photoshop-mcp-server start --bridge-mode uxp

5. 发送 API 请求时，将 bridge_mode 参数设为 uxp

POST /openFile
{
  "path": "/path/to/file.psd",
  "bridge_mode": "uxp"
}

UXP 插件安装详情

使用 UXP 插件需要 Adobe UXP Developer Tool。

安装 Adobe UXP Developer Tool

1. 从 Adobe UXP Developer Tool 下载最新版本
2. 运行下载的安装程序，并按照提示完成安装
3. 安装完成后，启动 Adobe UXP Developer Tool

插件安装步骤

1. 打包插件

   photoshop-mcp-server package_plugin
   

   这会在 dist/photoshop-mcp.zip 中创建插件包。

2. 在 UXP Developer Tool 中添加插件

   • 在 UXP Developer Tool 中点击“Add Plugin”按钮
   • 选择创建的 dist/photoshop-mcp.zip
   • 加载插件（点击“Load”按钮）

3. 在 Photoshop 中启用

   • 启动 Photoshop（如果已在运行，请重新启动）
   • 在插件菜单中选择“Photoshop MCP”以启用

4. 启动 MCP 服务（UXP 模式）

   photoshop-mcp-server start --bridge-mode uxp
   

5. 确认连接

   • 如果服务日志中显示“UXP Plugin connected”，则表示连接成功
   • 如果连接失败，请参阅故障排除

WebSocket 端点

使用 UXP 后端时，还可以使用 WebSocket 端点：

ws://localhost:5001/ws

可以通过 WebSocket 直接发送和接收 JSON 消息。

跨平台支持详情

从 v0.2.0 开始，Photoshop MCP Server 完全支持跨平台。新增了以下功能：

平台检测与抽象

platform_utils.py 模块提供以下功能：

• 平台检测函数（get_platform(), is_windows(), is_macos()）
• 平台专用配置（get_platform_config()）
• 平台专用临时文件管理（get_temp_file()）
• 根据平台进行条件分支处理（platform_specific 装饰器）

# プラットフォームに応じた処理の例
from photoshop_mcp_server.bridge.platform_utils import platform_specific

@platform_specific(
    windows_func=windows_specific_function,
    macos_func=macos_specific_function,
    default_func=default_function
)
def process_file(path):
    # プラットフォームに応じた関数が自動的に呼び出される
    pass

性能优化

• 通过脚本缓存提升执行速度（平均提速 30%）
• 脚本执行超时设置（默认 30 秒）
• 优化临时文件管理（自动清理）
• 优化并行处理（处理大量文件时提速 50%）
• 降低内存使用量（处理大型 PSD 文件时减少 40%）

v1.1 阶段的新功能

• 支持 UXP Plug-in 后端（WebSocket 通信）
• 插件打包功能
• 显示安装步骤的功能
• 扩展健康检查端点（确认 UXP 插件的连接状态）

v1.2 阶段的新功能

缩略图生成

• 用于从 PSD 文件生成缩略图的 REST 端点
• 按指定尺寸和格式（JPEG/PNG）生成缩略图
• 返回 Base64 编码的图像数据

POST /generateThumbnail
{
  "path": "/path/to/file.psd",
  "width": 256,
  "height": 256,
  "format": "jpeg",
  "quality": 80,
  "bridge_mode": "uxp"
}

WebSocket 流式传输

• 用于实时流式传输缩略图生成进度的 WebSocket 端点
• 通知各处理步骤（打开文件、生成缩略图、处理图像等）的进度
• 实时通知错误

WebSocketエンドポイント: ws://localhost:5001/generateThumbnail/stream

リクエスト:
{
  "path": "/path/to/file.psd",
  "width": 256,
  "height": 256,
  "format": "jpeg",
  "quality": 80,
  "bridge_mode": "uxp"
}

レスポンス（ストリーミング）:
{
  "type": "start",
  "data": { ... }
}
{
  "type": "progress",
  "data": { "step": "opening_file", "progress": 10, "message": "ファイルを開いています..." }
}
{
  "type": "progress",
  "data": { "step": "generating_thumbnail", "progress": 30, "message": "サムネイルを生成しています..." }
}
...
{
  "type": "complete",
  "data": { "width": 256, "height": 256, "format": "jpeg" }
}

v2.0 阶段的新功能

Cluster 模式

Cluster 模式用于管理多个 Photoshop 实例并分发处理任务。 此模式旨在高效处理大量图像任务。

主要功能

• 管理多个 Photoshop 实例（节点）
• 分发任务并进行负载均衡
• 自动故障转移
• 健康检查与监控
• 多种路由策略（最小负载、轮询、最小延迟等）

Clusterモードの使用方法

1. ディスパッチャーの起動

# ディスパッチャーを起動
photoshop-mcp-server start_cluster --host 127.0.0.1 --port 8001

2. ノードの起動

# ノード1を起動
photoshop-mcp-server start_node --host 127.0.0.1 --port 8002 --dispatcher 127.0.0.1:8001

# ノード2を起動
photoshop-mcp-server start_node --host 127.0.0.1 --port 8003 --dispatcher 127.0.0.1:8001

3. APIを使用したジョブの送信

POST http://127.0.0.1:8001/submit_job
{
  "job_type": "open_file",
  "payload": {
    "path": "/path/to/file.psd"
  },
  "priority": 1
}

設定例

# ディスパッチャー設定
dispatcher_config = {
    "host": "127.0.0.1",
    "port": 8001,
    "routing_strategy": "least_busy",  # least_busy, round_robin, random, lowest_latency, capability_based
    "node_timeout": 60.0,
    "job_timeout": 300.0,
    "health_check_interval": 30.0
}

# ノード設定
node_config = {
    "host": "127.0.0.1",
    "port": 8002,
    "dispatcher": "127.0.0.1:8001",
    "capabilities": ["open_file", "save_file", "export_layer", "run_action"],
    "max_concurrent_jobs": 5
}

LLM自動レタッチ機能

LLM自動レタッチ機能は、LiteLLMを使用して画像を分析し、自動的にレタッチを行う機能です。 GPT-4 Visionなどのマルチモーダルモデルを使用して画像を分析し、最適なレタッチパラメータを生成します。

主な機能

• 画像の自動分析
• レタッチパラメータの自動生成
• Photoshopアクションの自動実行
• カスタムプロンプトによる調整

LLM自動レタッチの使用方法

POST /autoRetouch
{
  "path": "/path/to/image.jpg",
  "instructions": "肌をなめらかにして、コントラストを上げてください",
  "bridge_mode": "uxp"
}

レスポンス:

{
  "analysis": {
    "basic_info": {
      "image_type": "ポートレート",
      "main_subject": "女性",
      "overall_impression": "自然光で撮影された屋外ポートレート"
    },
    "technical_characteristics": {
      "brightness": {
        "status": "やや暗い",
        "value": -15
      },
      "contrast": {
        "status": "弱い",
        "value": -20
      },
      ...
    },
    ...
  },
  "retouch_actions": [
    {
      "type": "brightness_contrast",
      "params": {
        "brightness": 15,
        "contrast": 20
      }
    },
    {
      "type": "skin_smoothing",
      "params": {
        "strength": 30,
        "detail": 50
      }
    },
    ...
  ],
  "execution_result": {
    "status": "success",
    "actions_applied": 5,
    "execution_time": 3.5
  }
}

カスタムプロンプトの例

この画像は屋外で撮影されたポートレートです。以下の点に注目してレタッチしてください：
1. 肌をなめらかにする（強さ: 中程度）
2. 目の明るさとコントラストを上げる
3. 背景をわずかにぼかす
4. 全体的な色調を暖かみのある雰囲気に調整する

MCPクライアント設定

Photoshop MCP ServerをAIアシスタントなどのMCPクライアントと連携するには、設定ファイルが必要です。

設定ファイルの構造

設定ファイルは通常mcp-config/photoshop-mcp-server.jsonに配置され、以下の構造を持ちます：

{
  "server_info": {
    "name": "photoshop-mcp-server",
    "description": "Photoshop MCP Server for macOS and Windows",
    "version": "0.2.0",
    "endpoint": "http://localhost:5001"
  },
  "tools": [
    {
      "name": "open_file",
      "description": "Open a file in Photoshop",
      "input_schema": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string",
            "description": "Path to the file"
          },
          "bridge_mode": {
            "type": "string",
            "description": "Bridge mode to use (applescript, powershell, uxp)",
            "default": "default"
          }
        },
        "required": ["path"]
      }
    },
    {
      "name": "save_file",
      "description": "Save the current file",
      "input_schema": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string",
            "description": "Path to save the file"
          },
          "format": {
            "type": "string",
            "description": "File format (psd, jpg, png, tiff)",
            "default": "psd"
          },
          "bridge_mode": {
            "type": "string",
            "description": "Bridge mode to use",
            "default": "default"
          }
        },
        "required": ["path"]
      }
    },
    {
      "name": "run_action",
      "description": "Run a Photoshop action",
      "input_schema": {
        "type": "object",
        "properties": {
          "action_set": {
            "type": "string",
            "description": "Action set name"
          },
          "action_name": {
            "type": "string",
            "description": "Action name"
          },
          "bridge_mode": {
            "type": "string",
            "description": "Bridge mode to use",
            "default": "default"
          }
        },
        "required": ["action_set", "action_name"]
      }
    },
    {
      "name": "generate_thumbnail",
      "description": "Generate a thumbnail from a PSD file",
      "input_schema": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string",
            "description": "Path to the PSD file"
          },
          "width": {
            "type": "integer",
            "description": "Thumbnail width",
            "default": 256
          },
          "height": {
            "type": "integer",
            "description": "Thumbnail height",
            "default": 256
          },
          "format": {
            "type": "string",
            "description": "Image format (jpeg, png)",
            "default": "jpeg"
          },
          "quality": {
            "type": "integer",
            "description": "Image quality (1-100)",
            "default": 80
          },
          "bridge_mode": {
            "type": "string",
            "description": "Bridge mode to use",
            "default": "default"
          }
        },
        "required": ["path"]
      }
    },
    {
      "name": "auto_retouch",
      "description": "Auto retouch an image using LLM",
      "input_schema": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string",
            "description": "Path to the image"
          },
          "instructions": {
            "type": "string",
            "description": "Retouch instructions"
          },
          "bridge_mode": {
            "type": "string",
            "description": "Bridge mode to use",
            "default": "default"
          }
        },
        "required": ["path", "instructions"]
      }
    }
  ],
  "resources": [
    {
      "uri": "photoshop://status",
      "description": "Get server status"
    },
    {
      "uri": "photoshop://version",
      "description": "Get server version"
    },
    {
      "uri": "photoshop://plugin/status",
      "description": "Get UXP plugin status"
    }
  ]
}

設定ファイルの配置

1. mcp-configディレクトリを作成（存在しない場合）
2. 上記の設定ファイルをmcp-config/photoshop-mcp-server.jsonとして保存
3. MCPクライアントがこの設定ファイルを読み込めるようにする

クライアント実装例

JavaScript (WebSocket)

// WebSocketを使用したサムネイル生成ストリーミング
const ws = new WebSocket('ws://localhost:5001/generateThumbnail/stream');

ws.onopen = () => {
  // リクエスト送信
  ws.send(JSON.stringify({
    path: '/path/to/file.psd',
    width: 256,
    height: 256,
    format: 'jpeg',
    quality: 80,
    bridge_mode: 'uxp'
  }));
};

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  
  switch (message.type) {
    case 'start':
      console.log('サムネイル生成開始:', message.data);
      break;
    case 'progress':
      console.log(`進捗: ${message.data.progress}% - ${message.data.message}`);
      updateProgressBar(message.data.progress);
      break;
    case 'complete':
      console.log('サムネイル生成完了:', message.data);
      break;
    case 'error':
      console.error('エラー:', message.data.message);
      break;
  }
};

ws.onerror = (error) => {
  console.error('WebSocketエラー:', error);
};

ws.onclose = () => {
  console.log('WebSocket接続終了');
};

Python (REST API)

import requests
import base64
from PIL import Image
import io

# サムネイル生成リクエスト
response = requests.post('http://localhost:5001/generateThumbnail', json={
    'path': '/path/to/file.psd',
    'width': 256,
    'height': 256,
    'format': 'jpeg',
    'quality': 80,
    'bridge_mode': 'uxp'
})

if response.status_code == 200:
    data = response.json()
    # Base64エンコードされた画像データをデコード
    image_data = base64.b64decode(data['thumbnail'])
    
    # PILで画像を開く
    image = Image.open(io.BytesIO(image_data))
    
    # 画像を保存
    image.save('thumbnail.jpg')
    print(f"サムネイル生成成功: {data['width']}x{data['height']} ({data['format']})")
else:
    print(f"エラー: {response.status_code} - {response.text}")

Python (Cluster API)

import requests

# ジョブの送信
response = requests.post('http://localhost:8001/submit_job', json={
    'job_type': 'auto_retouch',
    'payload': {
        'path': '/path/to/image.jpg',
        'instructions': '肌をなめらかにして、コントラストを上げてください'
    },
    'priority': 2
})

if response.status_code == 200:
    data = response.json()
    job_id = data['job_id']
    print(f"ジョブ送信成功: {job_id}")
    
    # ジョブのステータス確認
    status_response = requests.get(f'http://localhost:8001/job_status/{job_id}')
    if status_response.status_code == 200:
        status_data = status_response.json()
        print(f"ジョブステータス: {status_data['status']}")
else:
    print(f"エラー: {response.status_code} - {response.text}")

活用事例

Photoshop MCP Serverを使用すると、AIアシスタントやその他のアプリケーションからPhotoshopを自動制御できます。以下に主な活用事例を紹介します：

AIアシスタントによる画像編集の自動化

• プロンプトベースの画像編集

  • 「この写真の背景をぼかして、前景の人物を明るくして」といった自然言語指示でPhotoshopを操作
  • 複雑な編集手順を自然言語で指示し、AIがPhotoshopコマンドに変換して実行

• バッチ処理の自動化

  • 「フォルダ内の全画像に同じ編集を適用して」といった指示で複数ファイルを一括処理
  • 画像のリサイズ、フォーマット変換、フィルター適用などを自動化

LLM自動レタッチ機能

• 画像分析と自動補正

  • AIが画像を分析し、明るさ、コントラスト、彩度などの最適な調整値を自動決定
  • ポートレート写真の肌補正、風景写真の色調補正などを自動実行

• スタイル転送と創造的編集

  • 「この写真を夕暮れの雰囲気に編集して」といった指示でスタイル転送
  • AIが適切なレイヤー効果やフィルターを選択して適用

ワークフロー統合

• 他のツールとの連携

  • Webアプリケーションからの画像編集リクエスト処理
  • 画像管理システムとの連携による編集ワークフロー自動化

• バックグラウンド処理

  • ヘッドレスモードでの画像処理（UIなしで実行）
  • サーバー環境での大量画像処理

クラスターモードによる分散処理

• 複数Photoshopインスタンスの並列処理

  • 大量の画像を複数のPhotoshopインスタンスに分散して処理
  • 処理速度の大幅な向上と効率化

• 負荷分散と冗長性

  • 処理負荷に応じた動的なジョブ割り当て
  • 一部のノードが失敗しても処理を継続

具体的なユースケース

• Eコマース製品画像の一括処理

  • 背景除去、サイズ統一、ウォーターマーク追加などを自動化
  • 複数バリエーションの製品画像を一括生成

• 写真スタジオの後処理自動化

  • ポートレート写真の肌補正、色調調整を自動化
  • クライアント要望に基づいた編集スタイルの適用

• マーケティング素材の大量生成

  • 同じデザインテンプレートに異なるテキストや画像を適用
  • ソーシャルメディア用の複数サイズバリエーションを自動生成

• 画像アーカイブの最適化

  • 古い写真の復元や最適化を自動化
  • メタデータの追加と画像フォーマットの標準化

AIアシスタントとの連携

Photoshop MCP Serverは、AIアシスタントからPhotoshopを操作するためのインターフェースを提供します。

連携の仕組み

1. MCPクライアント設定ファイルをAIアシスタントに登録
2. AIアシスタントがMCPプロトコルを通じてPhotoshop MCP Serverと通信
3. Photoshop MCP ServerがPhotoshopを制御

サンプルプロンプト例

Photoshopで以下の操作を行ってください：
1. 画像ファイル "/path/to/image.jpg" を開く
2. 明るさとコントラストを調整して、画像を明るくする
3. 結果を "/path/to/output.jpg" として保存する

AIアシスタントのレスポンス例

Photoshopでの操作を実行します。

1. 画像ファイルを開きます...
   - ファイル: /path/to/image.jpg
   - ステータス: 成功

2. 明るさとコントラストを調整します...
   - 明るさ: +15
   - コントラスト: +10
   - ステータス: 成功

3. 結果を保存します...
   - 保存先: /path/to/output.jpg
   - 形式: JPEG
   - 品質: 90%
   - ステータス: 成功

すべての操作が正常に完了しました。

連携時の注意点

• AIアシスタントがローカルファイルシステムにアクセスできる必要があります
• ファイルパスは絶対パスで指定することを推奨
• 大きなファイルの処理には時間がかかる場合があります
• UXPプラグインを使用する場合は、Photoshopが起動している必要があります

トラブルシューティング

よくある問題と解決策

サーバー起動時のエラー

問題: サーバーが起動しない、または起動後すぐに終了する

解決策:

• ポート5001が他のアプリケーションで使用されていないか確認

  # macOS/Linux
  lsof -i :5001
  
  # Windows
  netstat -ano | findstr :5001
  

• 別のポートを指定して起動

  photoshop-mcp-server start --port 5002
  

• ログファイルを確認

  cat ~/.photoshop_mcp_server/logs/server.log
  

UXPプラグイン接続エラー

問題: UXPプラグインがサーバーに接続できない

解決策:

• Photoshopが起動していることを確認
• UXPプラグインが正しくインストールされていることを確認
• サーバーとプラグインが同じポートを使用していることを確認
• ファイアウォールがWebSocket接続をブロックしていないか確認
• サーバーを再起動し、Photoshopも再起動

AppleScript/PowerShellエラー

問題: AppleScriptまたはPowerShellバックエンドでエラーが発生する

解決策:

• Photoshopが起動していることを確認
• スクリプト実行権限を確認
  • macOS: sudo chmod +x /usr/bin/osascript
  • Windows: PowerShellの実行ポリシーを確認 Get-ExecutionPolicy
• デバッグモードで詳細なログを確認

  photoshop-mcp-server start --debug --foreground
  

ログファイルの場所

ログファイルは以下の場所に保存されます：

• macOS: ~/.photoshop_mcp_server/logs/
• Windows: %USERPROFILE%\.photoshop_mcp_server\logs\

主なログファイル：

• server.log: サーバーのメインログ
• api.log: APIリクエストとレスポンスのログ
• bridge.log: バックエンド（AppleScript/PowerShell/UXP）のログ
• cluster.log: Clusterモードのログ

サポートとフィードバック

問題が解決しない場合は、以下の情報を含めてGitHubのIssueを作成してください：

• 使用しているOS（バージョン含む）
• Photoshopのバージョン
• 実行したコマンド
• エラーメッセージ
• ログファイルの関連部分

ライセンス

MITライセンス

Copyright (C) 2025 StarBoze https://github.com/StarBoze