Lightroom Classic MCP Server

Model Context Protocol (MCP) server for Adobe Lightroom Classic. Provides AI agents and LLMs with comprehensive catalog management, develop adjustments, preview generation, and histogram analysis capabilities.

• 📚 Catalog Operations - Search photos, manage collections, extract metadata
• 🎨 Develop Tools - 114 RAW adjustment parameters across 49 commands with batch operations
• 🖼️ Preview Generation - JPEG thumbnails with automatic resizing and optimization
• 📊 Histogram Analysis - RGB and luminance histograms from preview data
• ⚡ Performance - Efficient batch operations and chunked transfers

Option A - Plugin Manager (Recommended):

1. In Lightroom: File → Plug-in Manager
2. Click "Add" and select lightroom-python-bridge.lrdevplugin

Option B - Manual Install: Copy lightroom-python-bridge.lrdevplugin to:

• Mac: ~/Library/Application Support/Adobe/Lightroom/Modules/
• Windows: %APPDATA%\Adobe\Lightroom\Modules\

In Lightroom: File → Plug-in Extras → Start Python Bridge

pip install -r requirements.txt

python -m mcp_server.main

Alternative execution methods:

# Direct execution
python mcp_server/main.py

# With virtual environment
./venv/bin/python -m mcp_server.main

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "lightroom": {
      "command": "python",
      "args": ["-m", "mcp_server.main"],
      "cwd": "/path/to/lightroom_mcp"
    }
  }
}

Claude Code via JSON

claude mcp add-json -s user Lightroom '{
    "command": "<path to repo>/lightroom_mcp/venv/bin/python",
    "args": ["<path to repo>/lightroom_mcp/mcp_server/main.py"],
    "env": {
      "PYTHONPATH": "<path to repo>/lightroom_mcp"
    }
  }'

Basic adjustments:

"Select the first RAW photo and increase exposure by +0.5, add some vibrance, and reduce highlights"

Batch processing:

"Find all photos from today and apply a warm tone preset: temperature +200K, tint +10, vibrance +20"

Advanced masking:

"Create an AI subject mask, brighten the subject by +0.3 exposure, then create a background mask and add subtle blur"

Tone curves:

"Apply a gentle S-curve to the main tone curve for more contrast, then warm up the highlights using the red channel curve"

Preview generation:

"Generate a medium-sized JPEG preview of the current photo and save it as 'hero_image.jpg'"

Histogram analysis:

"Analyze the RGB histogram of the current photo and tell me if it's properly exposed"

Organization:

"Show me all photos in the 'Portraits' collection taken with a 85mm lens"

System (2 tools): system_ping, system_status

Catalog (11 tools): Photo search, metadata extraction, folder/collection management, selection control

Develop (49 tools): All basic adjustments (exposure, contrast, etc.), tone curves, HSL/color, detail, lens corrections, effects, calibration, masking

Preview (4 tools): Generate optimized JPEGs with automatic PIL-based resizing

Histogram (3 tools): RGB, luminance, and full spectrum analysis

• Lightroom Classic 12.x or newer
• Python 3.8+
• Dependencies: FastMCP, Pillow, NumPy (see requirements.txt)

[AI Agent/LLM] ↔ [MCP Server] ↔ [Lightroom Plugin] ↔ [Lightroom Classic]

• Main Server: mcp_server/main.py - FastMCP composition layer
• Modular Servers: System, Catalog, Develop (9 modules), Preview
• Resilient Client: Auto-reconnection and timeout handling
• Error Middleware: Comprehensive error handling and validation
• Lightroom SDK: Type-safe Python client with structured exceptions

• Plugin: lightroom-python-bridge.lrdevplugin - Lua-based Lightroom extension
• Dual Sockets: JSON-RPC over TCP (LrSocket limitation requires separate send/receive)
• Command Router: Dynamic dispatch with 66 registered handlers
• Protocol: JSON with chunked transfer for large data (>10MB)

• Temperature and Tint parameters are set individually (not in batch) for compatibility
• Preview generation uses PIL for resizing since Lightroom returns full-resolution images
• Most develop operations require a photo to be selected in Lightroom and the Develop tab open
• Chunked transfer automatically handles large preview files (>10MB)

The server provides comprehensive error handling with structured exceptions:

Common Error Types:

• PhotoNotSelectedError - No photo selected in Lightroom
• ParameterOutOfRangeError - Parameter value outside valid range
• PhotoNotFoundError - Photo with given ID not found
• ConnectionError - Socket connection issues
• CatalogAccessError - Failed to access Lightroom catalog

Error Response Format:

{
  "error": {
    "code": "NO_PHOTO_SELECTED",
    "message": "Please select a photo in Lightroom",
    "severity": "error"
  }
}

Plugin Logs: Check Lightroom plugin activity and errors:

• Mac: ~/Logs/Adobe/Lightroom/LrClassicLogs/LightroomPythonBridge.log
• Windows: %USERPROFILE%\Logs\Adobe\Lightroom\LrClassicLogs\LightroomPythonBridge.log

Common Issues:

• Plugin not appearing: Restart Lightroom after installation
• Connection errors: Ensure bridge is started via File → Plug-in Extras → Start Python Bridge
• Parameter errors: Verify a photo is selected in Lightroom before develop operations

# Run Python tests
python -m pytest lightroom_sdk/tests/

# Test MCP server directly
python -c "from mcp_server.main import main_server; print('Server loaded successfully')"