Content
# photoshop-generator-mcp-server
[](https://nodejs.org/)
[](https://www.typescriptlang.org/)
[](https://modelcontextprotocol.io/)
[](https://opensource.org/licenses/MIT)
[](http://makeapullrequest.com)
[English](README.md) | [中文文档](README_zh.md)
An MCP (Model Context Protocol) server that bridges AI models to Adobe Photoshop via the Generator API. It runs as a Photoshop Generator plugin and exposes Photoshop capabilities through both the MCP protocol (Streamable HTTP) and WebSocket, enabling AI assistants like Claude Desktop to directly operate Photoshop.
> **Note**: This project is in active development. APIs may evolve; see changeset for version history.
> **In Progress**: More key Photoshop operations (layer editing, filters, selections, etc.) are being actively developed in the [`generator-tools`](packages/generator-tools/) package. Stay tuned for updates.
## Why This Project?
| Feature | Description |
|---------|-------------|
| **MCP Native** | Full MCP 2025-03-26 Streamable HTTP implementation via `@modelcontextprotocol/sdk` |
| **Dual Transport** | MCP (HTTP) for AI clients + WebSocket for programmatic control |
| **Skills System** | Zero-code tool registration via `SKILL.md` + `scripts/` (JSX / TypeScript) |
| **Remote Client SDK** | `generator-remote-sdk` package for Node.js programmatic access with PS DOM Proxy |
| **Extensible** | Custom skills in `packages/generator-tools/Custom/` — drop in and go |
| **Type Safe** | Full TypeScript codebase with Zod schema validation |
| **Production Ready** | Multi-session MCP, port conflict auto-retry, graceful shutdown |
AI-friendly docs: [docs/skills/](docs/skills/)
## Quick Start
### Prerequisites
- **Adobe Photoshop** 2021+ (with Generator enabled, see Running section below)
- **Node.js** >= 18
### Installation
```bash
# Clone the repository
git clone https://github.com/wojzj57/photoshop-generator-api-mcp-server
cd photoshopgenerator-api-mcp-server
# Initialize (clone generator-core + install dependencies)
npm run init
# Build all packages
npm run build
```
### Running
> **Note**: You must enable the Generator plugin option in Photoshop before testing or running (PS does not enable Generator by default).
> **Supported versions**: Photoshop 2021 and later.
#### 1. Configure Photoshop Generator Settings
Open the Photoshop preferences dialog, go to the **Plug-Ins** panel, and apply these settings:
- **Enable** the "Enable Generator" checkbox
- **Enable** the "Enable Remote Connections" checkbox
- Change the password to `password` (without quotes)
- **Restart Photoshop**
See the Generator Wiki for details: [Generator Development Environment Setup](https://github.com/adobe-photoshop/generator-core/wiki/Generator-Development-Environment-Setup)
#### 2. Development & Debugging
```bash
# Build all packages
npm run build
# Or watch mode (auto-recompile on changes)
npm run dev
# Start plugin for debugging
npm run run
```
#### 3. Package & Deploy
```bash
# Package the plugin
npm run pack
```
Copy the `output/` directory to the Photoshop installation's Generator plugin folder:
```
{Photoshop Install Dir}/Plug-ins/Generator/
```
Once started, the plugin exposes:
- **MCP endpoint**: `http://127.0.0.1:9010/mcp` (Streamable HTTP)
- **WebSocket**: `ws://127.0.0.1:9011`
- **Health check**: `http://127.0.0.1:9010/health`
> **Port Configuration**: You can modify ports and other key settings in the `generatorMcpConfig` field of `packages/generator-plugin/package.json`:
> ```json
> "generatorMcpConfig": {
> "httpPort": 9010,
> "wsPort": 9011,
> "host": "127.0.0.1",
> "jsxTimeout": 30000,
> "maxExportDimension": 4096
> }
> ```
### Configure in Claude Desktop
Add to your Claude Desktop `claude_desktop_config.json`:
```json
{
"mcpServers": {
"photoshop": {
"url": "http://127.0.0.1:9010/mcp"
}
}
}
```
## Architecture
### Monorepo Structure
This project is organized as an npm workspaces monorepo with three packages:
| Package | Description | Version |
|---------|-------------|---------|
| [`generator-plugin`](packages/generator-plugin/) | Core Photoshop Generator plugin with MCP server | 1.1.0 |
| [`generator-remote-sdk`](packages/generator-remote-sdk/) | Remote client SDK for programmatic access via WebSocket | 0.1.0 |
| [`generator-tools`](packages/generator-tools/) | Built-in skill modules (JSX + TypeScript handlers) | 1.1.0 |
Additionally:
- **`generator-core/`** — Vendored Adobe Generator Core v3.12.1 (MIT). Handles low-level TCP connection to Photoshop (port 49494), authentication, message framing, JSX evaluation, and plugin loading. **Read-only — do not modify.**
### Communication Flow
```
┌──────────────────────────────┐
│ AI Client (Claude Desktop) │
│ MCP Streamable HTTP │
└──────────────┬───────────────┘
│ POST http://127.0.0.1:9010/mcp
┌──────────────▼───────────────┐
│ McpBridge (MCP SDK) │ ← Fastify HTTP Transport
│ Single "call" tool │
│ Skills as MCP Resources │
├──────────────────────────────┤
│ ToolRegistry │ ← Unified tool registry
│ SkillScanner │ ← SKILL.md discovery & parsing
│ JsxEngine │ ← JSX script execution engine
├──────────────────────────────┤
│ WsTransport (ws://9011) │ ← WebSocket JSON-RPC + events
│ EventService │ ← PS event subscription management
├──────────────────────────────┤
│ generator-core │ ← Adobe open-source library
│ (TCP 127.0.0.1:49494) │
└──────────────┬───────────────┘
│ Binary protocol + crypto auth
┌──────────────▼───────────────┐
│ Adobe Photoshop │
│ ExtendScript Engine │
└──────────────────────────────┘
```
### Startup Sequence (Bootstrap)
1. `AppConfig` creation (Zod validation)
2. Logger initialization
3. `PluginContext` + `JsxEngine` construction
4. `SkillScanner` scan + `ToolRegistry` registration
5. `HttpTransport` (Fastify) initialization
6. `McpBridge` startup + route mounting
7. HTTP listen
8. `EventService` startup
9. `WsTransport` startup
10. Default PS event subscriptions (5 core events)
11. PS menu item registration
## Built-in Skills (Tools)
The `generator-tools` package provides the following built-in skills:
| Skill | Category | Tools | Description |
|-------|----------|-------|-------------|
| `app_alert` | App | `app_alert__alert` | Show alert dialog in Photoshop |
| `app_info` | App | `app_info__get`, `app_info__set` | Get/set application info |
| `app_jsx` | App | `app_jsx__run_jsx`, `app_jsx__run_jsx_file` | Execute JSX code/files |
| `document_info` | Document | `document_info__get`, `document_info__list` | Get document info / list open docs |
| `document_open` | Document | `document_open__open` | Open a document file |
| `document_save` | Document | `document_save__save`, `document_save__save_as` | Save / Save As |
| `export_png` | Export | `export_png__layer`, `export_png__document` | Export PNG images |
| `layer_info` | Layer | `layer_info__get`, `layer_info__list` | Get layer info / list layers |
### Tool Naming Convention
Each script in `scripts/` becomes a tool named `{skill_name}__{script_stem}`:
- `App/Info/scripts/get.jsx` → `app_info__get`
- `Document/Save/scripts/save_as.jsx` → `document_save__save_as`
## Skills System — Zero-Code Tool Registration
The Skills system lets you register any script (JSX or TypeScript) as an MCP-discoverable tool with **zero code**:
### How It Works
```
SKILL.md (metadata) + scripts/ directory
↓ SkillScanner discovers & parses
SkillManifest per skill (name, description, scripts)
↓ Tools registered in ToolRegistry → callable by AI via MCP
```
### Create a Custom Skill
**1. Create a skill directory in `packages/generator-tools/Custom/`:**
```
Custom/MyTool/
├── SKILL.md # Metadata + description
└── scripts/
└── action.jsx # Your ExtendScript
```
**2. Write `SKILL.md`:**
```yaml
---
name: "my_tool"
displayName: "My Custom Tool"
description: "Does something amazing in Photoshop"
category: "Custom"
version: "1.0.0"
---
# My Tool
Description of what this tool does for AI context.
```
**3. Add your script in `scripts/`:**
JSX files (`.jsx`) execute inside Photoshop's ExtendScript engine. TypeScript files (`.ts`) compile to `.js` and run as Node.js handlers with access to the full plugin context.
**4. Rebuild and restart.** The skill is automatically discovered and registered.
### Supported Script Types
| Extension | Type | Execution |
|-----------|------|-----------|
| `.jsx` | ExtendScript | Inside Photoshop scripting engine |
| `.js` / `.ts` | TypeScript handler | Node.js with `ToolContext` injection |
## Remote Client SDK
The `generator-remote-sdk` package provides a full-featured SDK for controlling Photoshop remotely:
```typescript
import { PsRemoteClient } from "generator-remote-sdk";
const ps = new PsRemoteClient({ url: "ws://127.0.0.1:9011" });
await ps.connect();
// Domain APIs
const { documentIds } = await ps.document.list();
const info = await ps.document.getInfo(documentIds[0]);
const { value } = await ps.jsx.execute("app.documents.length");
// Export
const { data, mimeType } = await ps.export.layerPng(docId, layerId);
// Tool invocation
const { tools } = await ps.tool.list();
const result = await ps.tool.invoke("app_alert__alert", { message: "Hello" });
// PS DOM Proxy
const version = await ps.photoshop.app.version;
const docName = await ps.photoshop.activeDocument.name;
await ps.photoshop.activeDocument.save();
// Events
ps.on("imageChanged", (data) => console.log(data));
await ps.events.subscribe(["imageChanged", "currentDocumentChanged"]);
// Connection state events
ps.on("$disconnected", (code) => console.warn("Disconnected:", code));
ps.on("$reconnecting", ({ attempt, delay }) => console.log(`Reconnecting...`));
await ps.disconnect();
```
### Remote Client Features
- **Domain APIs**: `document`, `layer`, `jsx`, `export`, `app`, `settings`, `skill`, `tool`, `events`
- **PS DOM Proxy**: `photoshop.app`, `photoshop.activeDocument` with familiar Photoshop DOM API
- **Auto-reconnect**: Exponential backoff with configurable max attempts
- **Connection state events**: `$connected`, `$disconnected`, `$reconnecting`, `$reconnectFailed`
- **Full TypeScript types**: Rich type definitions including complete Photoshop DOM types
## Configuration
Configuration priority (highest → lowest):
1. **Environment variables** (`MCP_HTTP_PORT`, `MCP_WS_PORT`, `MCP_HOST`, ...)
2. **package.json** → `generatorMcpConfig` field
3. **Zod schema defaults** (hard-coded fallback)
| Variable | Default | Description |
|----------|---------|-------------|
| `MCP_HTTP_PORT` | 9010 | HTTP/MCP server port |
| `MCP_WS_PORT` | 9011 | WebSocket server port |
| `MCP_HOST` | 127.0.0.1 | Bind host |
| `MCP_JSX_TIMEOUT` | 30000 | JSX execution timeout (ms) |
| `MCP_MAX_EXPORT_DIM` | 4096 | Max export image dimension (px) |
## Commands
| Command | Description |
|---------|-------------|
| `npm run init` | Initialize project (clone generator-core + install deps) |
| `npm run build` | Build all packages |
| `npm run dev` | Watch mode: recompile on changes |
| `npm run run` | Start as Photoshop Generator plugin (development) |
| `npm run test` | Run tests across all packages |
| `npm run clean` | Clean build artifacts |
| `npm run pack` | Package plugin for distribution (`output/`) |
## Development Setup
```bash
# Clone and initialize
git clone https://github.com/wojzj57/photoshop-generator-api-mcp-server
cd photoshopgenerator-api-mcp-server
npm run init
# Development mode (watch + auto-recompile)
npm run dev
# In another terminal, start the plugin
npm run run
# Run tests
npm run test
# Package for distribution
npm run pack
```
### Project Structure
```
photoshopgenerator-api-mcp-server/
├── packages/
│ ├── generator-plugin/ # MCP server + Generator plugin
│ │ ├── src/
│ │ │ ├── Bootstrap.ts # Startup orchestrator
│ │ │ ├── Transport/ # McpBridge, WsTransport, HttpTransport
│ │ │ ├── Tools/ # ToolRegistry
│ │ │ ├── Service/ # SkillScanner
│ │ │ ├── Application/ # EventService
│ │ │ ├── Infrastructure/ # AppConfig, JsxEngine, PluginContext
│ │ │ ├── shared/ # Shared type definitions
│ │ │ └── types/ # TypeScript type definitions
│ │ ├── main.js # Plugin entry point
│ │ └── package.json
│ ├── generator-remote-sdk/ # WebSocket remote client SDK
│ │ ├── src/
│ │ │ ├── PsRemoteClient.ts # Main client class
│ │ │ ├── api/ # Domain API classes
│ │ │ ├── photoshop/ # PS DOM Proxy
│ │ │ └── types.ts # Type definitions
│ │ └── package.json
│ └── generator-tools/ # Built-in skills (JSX + TypeScript handlers)
│ ├── App/ # Alert, Info, Jsx skills
│ ├── Document/ # Info, Open, Save skills
│ ├── Export/ # PNG export skill
│ ├── Layer/ # Layer info skill
│ ├── Custom/ # User custom skills (drop-in)
│ ├── shared/ # Shared utility functions
│ └── polyfills/ # ES3 polyfills for ExtendScript
├── generator-core/ # Adobe Generator Core (vendored, read-only)
├── docs/ # Documentation & AI agent skills
│ └── skills/ # Photoshop Script API, Generator & MCP Server references
├── scripts/ # Build & init scripts
└── package.json # Workspace root
```
## Release Process
This project uses [Changesets](https://github.com/changesets/changesets) for version management:
```bash
npm run changeset # Stage a changeset entry
npm run version # Bump versions based on changesets
```
## Commit Message Format
| Prefix | Description | Version Bump |
|--------|-------------|-------------|
| `feat:` | New feature | Minor (`0.x.0`) |
| `fix:` | Bug fix | Patch (`0.0.x`) |
| `feat!:` or `BREAKING CHANGE:` | Breaking change | Major (`x.0.0`) |
| `docs:` / `chore:` / `ci:` / `refactor:` / `test:` | No release triggered |
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
1. Fork the repository and clone your fork
2. Create a feature branch: `git checkout -b feat/my-feature`
3. Make your changes
4. Run tests: `npm run test`
5. Commit and push
6. Open a Pull Request
## License
This project is licensed under the MIT License.
`generator-core/` is a vendored copy of [Adobe Generator Core](https://github.com/peterflynn/generator-core) v3.12.1, also MIT licensed.
## AI Agent Resources
If you're an AI coding agent, also see:
- **[docs/skills/](docs/skills/)** — Photoshop Script API, Generator API & MCP Server reference skills
