Photoshop-MCP-服务器

Name: Photoshop-MCP-服务器
Author: StarBoze

作者：StarBoze7 星标更新：2025-05-04

安装使用来源：spider==github.com

项目介绍

Photoshop MCP Server

Model Context Protocol (MCP) 服务器用于在 macOS 和 Windows 上远程控制 Photoshop 的项目。

概述

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

macOS

AppleScript 后端 - 所有 Photoshop 版本均适用
UXP 插件后端 - Photoshop CC 2021 及以上版本适用（WebSocket 通信）

Windows

PowerShell 后端 - 所有 Photoshop 版本均适用
UXP 插件后端 - Photoshop CC 2021 及以上版本适用（WebSocket 通信）

功能

使用 FastAPI/Starlette 实现 REST/WebSocket 端点
支持跨平台（macOS/Windows）
使用 AppleScript/PowerShell 后端控制 Photoshop
使用 UXP 插件后端控制 Photoshop（WebSocket 通信）
插件打包功能
生成缩略图功能（支持 WebSocket 流式传输）
使用集群模式管理多个 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: 进程管理（集群模式）
grpcio: gRPC 通信（集群模式）
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 后端需要以下步骤：

打包 UXP 插件

photoshop-mcp-server package_plugin

显示 UXP 插件的安装步骤

photoshop-mcp-server install_plugin

根据显示的步骤安装插件
启动服务器并启用 UXP 后端

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

发送 API 请求时设置 bridge_mode 参数为 uxp

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

UXP 插件安装详情

使用 UXP 插件需要 Adobe UXP 开发工具。

安装 Adobe UXP 开发工具

从 Adobe UXP 开发工具下载最新版本
运行下载的安装程序并按照指示进行安装
安装完成后启动 Adobe UXP 开发工具

插件安装步骤

打包插件
```
photoshop-mcp-server package_plugin
```
这将创建一个位于 dist/photoshop-mcp.zip 的插件包。
在 UXP 开发工具中添加插件
- 在 UXP 开发工具中点击“添加插件”按钮
- 选择创建的 dist/photoshop-mcp.zip
- 加载插件（点击“加载”按钮）
在 Photoshop 中启用插件
- 启动 Photoshop（如果已启动则重新启动）
- 从插件菜单中选择“Photoshop MCP”以启用

启动 MCP 服务器（UXP 模式）

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

确认连接
- 如果服务器日志中显示“UXP 插件已连接”，则连接成功
- 如果连接失败，请参阅故障排除

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 插件后端（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 版的新功能

集群模式

集群模式是一种管理多个 Photoshop 实例并分散处理任务的功能。设计用于高效处理大量图像处理任务。

主要功能

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

使用集群模式的方法

启动调度器

# 启动调度器
photoshop-mcp-server start_cluster --host 127.0.0.1 --port 8001

启动节点

# 启动节点 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

使用 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": "成功",
    "actions_applied": 5,
    "execution_time": 3.5
  }
}

自定义提示示例

这张照片是在户外拍摄的肖像。请注意以下几点进行修图：
1. 使皮肤更光滑（强度：中等）
2. 提高眼睛的亮度和对比度
3. 稍微模糊背景
4. 调整整体色调，使其具有温暖的感觉

MCP 客户端配置

为了将 Photoshop MCP Server 与 MCP 客户端（如 AI 助手）集成，需要配置文件。

配置文件结构

配置文件通常位于 mcp-config/photoshop-mcp-server.json，其结构如下：

{
  "server_info": {
    "name": "photoshop-mcp-server",
    "description": "适用于 macOS 和 Windows 的 Photoshop MCP Server",
    "version": "0.2.0",
    "endpoint": "http://localhost:5001"
  },
  "tools": [
    {
      "name": "open_file",
      "description": "在 Photoshop 中打开文件",
      "input_schema": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string",
            "description": "文件路径"
          },
          "bridge_mode": {
            "type": "string",
            "description": "使用的桥接模式（applescript, powershell, uxp）",
            "default": "default"
          }
        },
        "required": ["path"]
      }
    },
    {
      "name": "save_file",
      "description": "保存当前文件",
      "input_schema": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string",
            "description": "保存文件的路径"
          },
          "format": {
            "type": "string",
            "description": "文件格式（psd, jpg, png, tiff）",
            "default": "psd"
          },
          "bridge_mode": {
            "type": "string",
            "description": "使用的桥接模式",
            "default": "default"
          }
        },
        "required": ["path"]
      }
    },
    {
      "name": "run_action",
      "description": "运行 Photoshop 动作",
      "input_schema": {
        "type": "object",
        "properties": {
          "action_set": {
            "type": "string",
            "description": "动作集名称"
          },
          "action_name": {
            "type": "string",
            "description": "动作名称"
          },
          "bridge_mode": {
            "type": "string",
            "description": "使用的桥接模式",
            "default": "default"
          }
        },
        "required": ["action_set", "action_name"]
      }
    },
    {
      "name": "generate_thumbnail",
      "description": "从 PSD 文件生成缩略图",
      "input_schema": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string",
            "description": "PSD 文件路径"
          },
          "width": {
            "type": "integer",
            "description": "缩略图宽度",
            "default": 256
          },
          "height": {
            "type": "integer",
            "description": "缩略图高度",
            "default": 256
          },
          "format": {
            "type": "string",
            "description": "图像格式（jpeg, png）",
            "default": "jpeg"
          },
          "quality": {
            "type": "integer",
            "description": "图像质量（1-100）",
            "default": 80
          },
          "bridge_mode": {
            "type": "string",
            "description": "使用的桥接模式",
            "default": "default"
          }
        },
        "required": ["path"]
      }
    },
    {
      "name": "auto_retouch",
      "description": "使用 LLM 对图像进行自动修图",
      "input_schema": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string",
            "description": "图像路径"
          },
          "instructions": {
            "type": "string",
            "description": "修图指令"
          },
          "bridge_mode": {
            "type": "string",
            "description": "使用的桥接模式",
            "default": "default"
          }
        },
        "required": ["path", "instructions"]
      }
    }
  ],
  "resources": [
    {
      "uri": "photoshop://status",
      "description": "获取服务器状态"
    },
    {
      "uri": "photoshop://version",
      "description": "获取服务器版本"
    },
    {
      "uri": "photoshop://plugin/status",
      "description": "获取 UXP 插件状态"
    }
  ]
}

配置文件位置

创建 mcp-config 目录（如果不存在）
将上述配置文件保存为