@onesitatech/photoshop-fabric-mcp-server

🚀 Version 2.0.0 - Complete Architecture Overhaul

A professional-grade MCP (Model Context Protocol) server that provides Claude with direct control over Adobe Photoshop 2025+ for hyper-realistic fabric transformations, advanced physics simulation, and professional garment modifications.

🏗️ Correct MCP Architecture (v2.0.0)

Claude Desktop ↔ MCP Server (STDIO) ↔ File System ↔ UXP Plugin ↔ Photoshop 2025

✅ Direct STDIO Communication - Follows official MCP standards
✅ No Network Dependencies - File-based UXP communication
✅ Zero HTTP Proxies - Simplified, standards-compliant approach

🎯 Version 2.0.0 Features

🧬 Hyper-Realistic Fabric Physics

• Advanced Physics Simulation: 7 fabric types with material properties
  • Silk (elasticity: 0.9, flexibility: 0.95)
  • Cotton (elasticity: 0.6, flexibility: 0.7)
  • Denim, Leather, Wool, Linen, Synthetic
• Wind & Gravity Effects: Realistic environmental simulation
• Material-Specific Deformation: Fabric behavior based on physical properties

💡 Professional Lighting System

• 5 Lighting Types: Natural, Studio, Dramatic, Soft, Golden
• Material-Based Light Interaction:
  • Silk: High reflectance (0.8), low roughness (0.1)
  • Cotton: Medium reflectance (0.4), higher roughness (0.6)
• Advanced Effects: Ambient occlusion, specular highlights, subsurface scattering

🎨 Advanced Surface Systems

• Realistic Fiber Texturing: Cotton, silk, wool, linen, denim, synthetic
• Weave Pattern Engine: Plain, twill, satin, herringbone, houndstooth, basket
• Thread Count Control: 50-500 threads per inch precision
• Surface Aging: Material wear and aging effects

🔬 Professional Deformation Tools

• Liquify Fabric Deformation: 5 fabric-specific modes
• Wave Deformation: Natural fabric flow and draping
• Spherize Body Contours: Realistic body curve mapping
• Polar Coordinates: Circular wrapping (sleeves, collars, cuffs)
• Puppet Warp Enhanced: Multi-pin professional deformation

🎯 50+ Professional Tools

• Master Fabric Transformation: Complete professional pipeline
• Advanced Blending Modes: Fabric-specific compositing
• Luminosity Masking: Precise tonal adjustments
• Smart Sharpening: Fabric detail enhancement
• Noise Reduction: Texture-preserving cleanup

🔥 Adobe Firefly Integration

• Generative Fill: AI-powered content generation
• Texture Matching: Seamless fabric texture generation
• Style Transfer: Reference-based fabric adaptation

📊 Quality & Performance

• 4 Quality Levels: Draft, High, Ultra, Professional
• Multi-Iteration Processing: 1-10 refinement passes
• Batch Operations: Multiple image processing
• Real-time Monitoring: UXP plugin status tracking

📦 Installation (v2.0.0)

Prerequisites

• Adobe Photoshop 2025 (26.0) or higher ⚠️ REQUIRED
• UXP Developer Tool for plugin loading
• Node.js 18+ for MCP server
• Windows/macOS/Linux (file-based communication)

Quick Start

# Install the MCP server
npm install -g @onesitatech/photoshop-fabric-mcp-server

# The server uses STDIO - no additional setup needed!

Install from source

git clone https://github.com/sagarnabhoya/photoshop-mcp-server.git
cd photoshop-mcp-server
npm install
npm run build

🚀 Quick Start

1. Configure Adobe Photoshop

• Ensure Photoshop is installed in the default location
• Enable ExtendScript execution in Photoshop preferences
• Sign in to Adobe Creative Cloud for Firefly access

2. Configure Claude Desktop

Add to your Claude Desktop configuration file (claude_desktop_config.json):

{
  "mcpServers": {
    "photoshop-fabric": {
      "command": "npx",
      "args": ["@onesitatech/photoshop-fabric-mcp-server"],
      "env": {
        "PHOTOSHOP_PATH": "C:/Program Files/Adobe/Adobe Photoshop 2025/Photoshop.exe"
      }
    }
  }
}

3. Start Using

Claude, I want to change the fabric of this shirt in my image. 
I have a model photo and want to apply a denim pattern.

1. Open my model image: "/path/to/model.jpg"
2. Load the denim patterns from my patterns folder
3. Apply hyper-realistic fabric transformation preserving all shadows and wrinkles
4. Export as high-quality PNG

🛠️ Available Tools

Document Operations

• create_document - Create new Photoshop documents
• open_document - Open existing files (PSD, JPG, PNG, etc.)
• save_document - Save in multiple formats with quality options
• get_document_info - Get document properties and metadata

Layer Management

• create_layer - Create layers with blend modes and opacity
• duplicate_layer - Duplicate existing layers
• merge_layers - Merge multiple layers intelligently
• set_layer_visibility - Show/hide layers
• set_layer_blend_mode - Change blend modes
• set_layer_opacity - Adjust layer transparency
• list_layers - Get all layer information
• get_layer_info - Detailed layer properties

Selection Tools

• make_selection - All selection types (rectangular, elliptical, lasso, magic wand, color range)
• modify_selection - Expand, contract, feather, smooth selections
• save_selection - Save selections as alpha channels
• load_selection - Load saved selections

Transformations

• transform_layer - Scale, rotate, skew, distort, perspective, flip
• puppet_warp - Advanced puppet warp with multiple pins and modes

Fabric-Specific Tools

• apply_fabric_pattern - Apply patterns with realistic body mapping
• extract_garment_lighting - Extract lighting information from garments
• create_displacement_map - Generate displacement maps for 3D effects
• hyper_realistic_fabric_swap - Complete fabric transformation pipeline

Advanced Fabric Tools

• liquify_fabric_deformation - Professional liquify deformation for fabric flow
• wave_deformation_filter - Natural fabric draping effects
• fabric_fiber_texturing - Add realistic fiber textures
• fabric_weave_pattern - Apply weave patterns (plain, twill, satin)
• master_fabric_transformation - Complete professional-grade pipeline

Pattern Management

• list_photoshop_patterns - Show all patterns in Photoshop's built-in library
• apply_photoshop_pattern - Apply built-in Photoshop patterns to layers

Batch Operations

• batch_fabric_transformation - Process multiple images automatically

📚 Usage Examples

Basic Fabric Transformation

await callTool('hyper_realistic_fabric_swap', {
  modelImage: '/path/to/model.jpg',
  newFabricPattern: 'denim_blue_001',
  preserveOriginalShading: true,
  preserveWrinkles: true,
  outputQuality: 'ultra',
  iterations: 5
});

Advanced Pattern Application

await callTool('apply_fabric_pattern', {
  modelLayerName: 'Model Layer',
  garmentSelection: 'Dress Selection',
  patternName: 'silk_floral_001',
  patternScale: 85,
  wrapIntensity: 70,
  blendMode: 'multiply'
});

Batch Processing

await callTool('batch_fabric_transformation', {
  inputDirectory: '/path/to/models/',
  outputDirectory: '/path/to/output/',
  fabricPattern: 'cotton_stripes_blue',
  settings: {
    preserveShading: true,
    outputFormat: 'PNG',
    quality: 'high'
  }
});

🎨 Supported Fabric Types

The system automatically categorizes fabric patterns:

• Cotton: Canvas, denim, chambray, poplin
• Silk: Satin, chiffon, crepe, dupioni
• Wool: Tweed, herringbone, flannel, cashmere
• Leather: Smooth, textured, exotic skins
• Synthetic: Polyester, nylon, blends
• Knits: Jersey, ribbing, cable knit
• Lace: Floral, geometric, vintage patterns

🔧 Configuration

Environment Variables

• PHOTOSHOP_PATH - Path to Photoshop executable
• OUTPUT_QUALITY - Default output quality (draft|high|ultra)
• MAX_ITERATIONS - Maximum refinement iterations

Adding Patterns to Photoshop

1. Open Photoshop
2. Go to Window > Patterns
3. Load pattern libraries using the gear icon
4. Patterns are now available to the MCP server automatically

🐛 Troubleshooting

Common Issues

1. Photoshop Not Found

   Error: Photoshop executable not found

   • Verify PHOTOSHOP_PATH in configuration
   • Ensure Photoshop 2024+ is installed

2. ExtendScript Errors

   Error: Script execution failed

   • Enable ExtendScript execution in Photoshop preferences
   • Check Windows/macOS security settings

3. Pattern Not Found Issues

   Error: Pattern 'fabric_001' not found

   • Use list_photoshop_patterns to see available patterns
   • Add patterns via Photoshop's Window > Patterns panel

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Wiki

🚀 Roadmap

• [ ] Support for more fabric types
• [ ] Real-time preview mode
• [ ] Integration with more design tools
• [ ] Cloud-based pattern library
• [ ] AI-powered fabric detection

Note: This MCP server requires Adobe Photoshop and Creative Cloud subscription. Firefly features require internet connection and may have usage limits based on your subscription tier.