Higgsfield Photoshop MCP

Local MCP server for inspecting and editing Adobe Photoshop documents. Supports layers, text, selections, masks, vector shapes, embedded Smart Objects, adjustments, filters, image previews and PSD/PNG/JPEG output.

Requirements

• Node.js 24 or later.
• Adobe Photoshop installed on the same computer as the MCP client.
• Tested on macOS with Photoshop 27.10.0. Windows support is experimental.

Installation

npm install --global @higgsfield_org/photoshop-mcp
fnf-photoshop doctor
fnf-photoshop config

Add the server entry printed by config to your MCP client's configuration, preserving existing entries. It uses absolute Node and server paths. Reconnect the client after registration. config does not change client settings itself.

Open Photoshop, then check the connection:

fnf-photoshop probe

On macOS, allow Automation access for the application launching the MCP. No Adobe panel or extension is required. The stdio executable is fnf-photoshop-mcp.

Tools

| Tool | Purpose | | -------------------- | ----------------------------------------------------------- | | ps_document_info | Inspect the active document. | | ps_catalog | List 78 operations and retrieve exact argument schemas. | | ps_do | Execute a catalog operation. | | ps_preview | Return a document image preview. | | ps_guide | Read editing and targeting instructions. | | ps_get_skill | Index and read bundled Photoshop workflows and references. | | ps_get_skill_asset | Resolve a bundled asset or script to a verified local path. | | ps_status | Inspect local connection state. |

Call ps_get_skill without arguments to discover any specialized workflows in the installed version; an empty index means use ps_guide. Asset paths returned by ps_get_skill_asset exist on this computer only. Reading a skill does not prove Photoshop is connected or that every described operation is supported.

Use document and layer IDs from inspection results. Text sizes are points; image dimensions and positions are pixels. Save/export requires a new absolute path. batch.run executes sequentially and stops on error without rolling back completed steps. Filters require compatible layers. Set ADOBE_MCP_READONLY=1 in the server environment to disable mutations, exports and previews.

Troubleshooting and limits

doctor checks local prerequisites; probe reads Photoshop. Verify a tool call in the MCP client after registration. Calls are serialized across clients. BUSY means another call or an unresolved prior call owns the lock.

OS_SCRIPT_NOT_STARTED means an OS permission or executable problem prevented dispatch; correct it and retry. A timeout may leave a script running. Inspect Photoshop before recovering ~/.higgsfield-adobe/photoshop.lock; do not remove it while execution is active or blindly repeat edits. Native errors may leave partial changes.

Rich-text ranges, linked Smart Objects, advanced gradients and general undo transactions are not supported. Windows uses PowerShell/COM; organization policy may restrict script execution.