Content
# Photoshop Agent
**Autonomous AI graphic designer that bridges AI reasoning with Adobe Photoshop via MCP.**
This agent exposes **two MCP server integrations** — **Photoshop MCP** (direct COM/ExtendScript control of the local Photoshop application) and **Adobe MCP** (Adobe Firefly + Photoshop REST API) — into a single, unified toolset for AI assistants like **OpenCode** and **Claude Code**.
---
## What It Is
The Photoshop Agent is a pure **MCP (Model Context Protocol) server** — no GUI, no website, no localhost UI. You configure it as a tool provider in OpenCode or Claude Code, and then your AI assistant can:
- Open, create, and modify Photoshop documents
- Apply adjustments, filters, textures, and layer effects
- Generate images via Adobe Firefly, Stable Diffusion, DALL-E, or Midjourney
- Search the web for textures and place them automatically
- Design complex production-grade PSDs from a natural language prompt
---
## Capabilities
- **Photoshop MCP** — 78 tools: document ops, layers, adjustments, filters, text, selections, transforms, exports, batch operations, history, and texture fetching
- **Adobe MCP** — Adobe Firefly text-to-image, generative fill/expand, plus the Adobe Photoshop REST API for cloud operations
- **Design Intelligence** — intent parsing, design classification, 12‑phase workflow engine, knowledge base (color theory, composition, typography, lighting, texture)
- **Multi-Provider AI Generation** — Stable Diffusion, DALL-E, Midjourney, Replicate, Adobe Firefly
- **Web Texture Fetching** — search and download textures from the web via Tavily API, place them with automatic blend modes and opacity
- **Non-Destructive** — adjustment layers, smart objects, backup creation, safety confirmations
---
## Architecture
```
OpenCode / Claude Code
│
├── MCP Protocol (stdio)
│
▼
Photoshop MCP Server (localhost)
│
├── Photoshop COM Bridge (PowerShell / JSX)
├── Adobe Firefly API
├── AI Generation (SD / DALL-E / Midjourney)
├── Web Search (Tavily)
└── Design Reasoner (knowledge base)
```
### Modules
| Module | Path | Description |
|--------|------|-------------|
| Agent Brain | `src/agent/` | 7-phase design pipeline orchestrator |
| Design Reasoner | `src/reasoning/` | 6-phase generative reasoning engine |
| Knowledge Base | `src/knowledge/` | Color theory, composition, typography, lighting, texture, formats |
| Workflows | `src/workflows/` | Template engine and quality validation |
| Templates | `src/templates/` | Production plans for 10 design types |
| Automation | `src/automation/` | Photoshop COM + ExtendScript execution |
| MCP Server | `src/mcp_server/` | 78 MCP tools (Photoshop + Adobe + Web) |
| AI Generation | `src/ai_generation/` | Multi-provider image generation |
| Cloud API | `src/cloud_api/` | Adobe Firefly + Photoshop REST API |
| Plugin System | `src/plugins/` | Extensible hooks and skills |
---
## Quick Start
### Prerequisites
- **Windows** (Photoshop COM automation requires Windows)
- **Adobe Photoshop 2022+** (tested with 2025 / 26.x)
- **Python 3.11+** (recommended: install with [uv](https://docs.astral.sh/uv/))
- **Git**
- **OpenCode** or **Claude Code** installed
### Installation
```bash
git clone https://github.com/cryxservices-glitch/Photoshop-Agent.git
cd Photoshop-Agent
# Create virtual environment
uv venv
.venv\Scripts\activate
# Install core dependencies (no GUI — pure MCP server)
uv pip install -e .
# Copy environment template
copy .env.example .env
```
### Configure for OpenCode
Add to your OpenCode config (`~/.config/opencode/opencode.json` or project `opencode.json`):
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"photoshop-agent": {
"type": "local",
"command": ["uv", "run", "-m", "src.mcp_server.server", "--stdio"],
"enabled": true
}
}
}
```
### Configure for Claude Code
Add to your Claude Desktop config:
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"photoshop-agent": {
"command": "uv",
"args": ["run", "-m", "src.mcp_server.server", "--stdio"],
"env": {
"PYTHONIOENCODING": "utf-8"
}
}
}
}
```
### Verify the Server Works
```bash
uv run -m src.mcp_server.server --stdio
```
Then restart OpenCode or Claude Code. The 78 MCP tools will be available. You can now prompt:
> "Open Photoshop and create a new 2000x2000 document"
> "Apply a vintage grunge effect to the active document"
> "Search for a paper texture and place it as a multiply layer at 30%"
> "Design a cyberpunk poster with neon colors and grid layout"
---
## Usage Examples
### Design a Complete Album Cover
In OpenCode/Claude Code, type:
> "Design a dark Y2K album cover, 3000x3000, neon green text, grain texture"
The agent will:
1. Parse your intent (format, style, mood, dimensions)
2. Classify the design type (album cover)
3. Generate a detailed production plan with layer groups (00-09)
4. Execute each step in Photoshop using MCP tools
5. Apply textures, typography, color grading, and export settings
### Apply an Effect
> "Add a vintage grunge print effect to the active document"
The agent will create 10+ effect layers (sepia, grain, paper texture, vignette, scratches, age stains, rough edge) grouped together.
### Fetch and Place a Texture
> "Fetch a grunge paper texture and apply it as multiply at 25% opacity"
Behind the scenes, the agent calls `photoshop_fetch_and_place_texture` which:
1. Searches the web (via Tavily API) — or falls back to curated texture URLs
2. Downloads the image to a temp file
3. Places it in the active document
4. Sets blend mode (multiply) and opacity (25%) automatically
---
## Environment Variables
Copy `.env.example` to `.env`. All are optional but some features require them:
| Variable | Required For | Purpose |
|----------|-------------|---------|
| `OPENAI_API_KEY` | No | LLM / DALL-E |
| `ANTHROPIC_API_KEY` | No | LLM via Claude |
| `NVIDIA_NIM_API_KEY` | No | NVIDIA NIM LLM |
| `OPENROUTER_API_KEY` | No | OpenRouter LLM |
| `TAVILY_API_KEY` | No | Web search (texture fetching) |
| `ADOBE_API_KEY` | No | Adobe Firefly / Cloud API |
| `REPLICATE_API_TOKEN` | No | Replicate API |
| `MIDJOURNEY_API_KEY` | No | Midjourney API |
| `AGENT_MODE` | No | `manual`, `assisted`, or `auto` |
No API keys required for manual mode — the agent uses built-in knowledge alone.
---
## MCP Tools (78 Total)
| Category | Tools |
|----------|-------|
| **Document** (5) | create, open, save, close, get info |
| **Layer** (10) | create, delete, rename, duplicate, mask, blend, opacity, visibility, merge, rasterize |
| **Adjustment** (7) | curves, levels, color balance, hue/sat, brightness/contrast, photo filter, sharpen |
| **Filter** (8) | gaussian blur, motion blur, lens blur, lens flare, add noise, desaturate, invert, auto levels |
| **Organization** (6) | auto-organize, group, flatten, merge visible, sort, color-code |
| **Selection** (8) | select rect/ellipse, select all, deselect, inverse, feather, expand, contract, save/load |
| **Text** (6) | create text, set font/size/color, alignment, update content |
| **Transform** (6) | scale, rotate, move, flip, fit to canvas, move to position |
| **Export** (5) | PNG, JPEG, TIFF, PDF, PSD |
| **Batch** (4) | batch rename, batch blend mode, batch export groups, batch opacity |
| **History** (4) | undo, redo, get history, clear history |
| **Windows Desktop** (8) | file ops, process control, system info, launch app |
| **🖼 Texture Fetch** (1) | search web + download + place with blend mode and opacity |
---
## Safety
- **Confirmation required** — destructive actions require explicit approval
- **Backup creation** — originals duplicated before edits
- **Non-destructive** — adjustment layers and smart objects preferred
- **Audit logging** — all automation actions timestamped
- **Opt-out** — set `AGENT_MODE=manual` to disable all automation
---
## Troubleshooting
| Issue | Fix |
|-------|-----|
| **COM errors / "Photoshop is busy"** | Dismiss modal dialogs in Photoshop. Restart if needed. |
| **"Cannot create ActiveX component"** | Run as Administrator. Ensure Photoshop is installed. |
| **MCP server not starting** | Check Python dependencies. Run `python -m src.mcp_server.server --stdio` manually. |
| **Photoshop not detected** | Confirm Photoshop is installed and running. |
| **Texture fetch fails** | Set `TAVILY_API_KEY`. Without it, only curated fallbacks work (grunge, paper, noise, vintage, metal, wood, fabric). |
---
## Development
```bash
# Run tests
uv run pytest tests/ -q
# Start MCP server manually
uv run -m src.mcp_server.server --stdio
# Generate a design plan (CLI only, no Photoshop needed)
uv run -m src.agent.main --prompt "Design an album cover"
```
### Project Layout
```
Photoshop-Agent/
├── src/
│ ├── agent/ Core agent (brain, parser, classifier, planner, designer)
│ ├── reasoning/ Generative design reasoner
│ ├── knowledge/ Design principles (color, composition, typography, etc.)
│ ├── workflows/ Engine, templates, validators
│ ├── templates/ Production plan templates for 10 design types
│ ├── automation/ Photoshop COM + ExtendScript execution
│ ├── mcp_server/ MCP protocol server + 78 tools
│ ├── ai_generation/ Multi-provider AI image generation
│ ├── cloud_api/ Adobe Firefly + Photoshop REST API
│ ├── plugins/ Extensible plugin/skills system
│ └── collaborative/ Real-time collab bridge
├── docs/ Documentation and architecture SVG diagrams
├── examples/ Workflow examples
├── scripts/ Utility scripts
└── tests/ Test suite (103+ tests)
```
---
## License
MIT — See [LICENSE](LICENSE).
