Lightroom Classic Server

WIP warning: this project now supports a minimal local Lightroom Classic workflow, but it is not a full automation suite. Use a single test image first, and keep imports/exports scoped to explicit files, selections, or collections.

Unofficial Lightroom Classic MCP server for local Adobe Lightroom Classic automation. It gives MCP clients such as Claude Desktop, Codex, ChatGPT-compatible MCP hosts, and other Model Context Protocol clients a structured way to queue non-generative Lightroom Classic work on your own computer.

This project is also discoverable as an Adobe Lightroom Classic MCP server, MCP for Lightroom Classic, and Claude/Codex/ChatGPT Lightroom Classic automation bridge.

Unofficial Project

This is not Adobe software. It is not affiliated with, endorsed by, sponsored by, or supported by Adobe. Adobe, Lightroom, and Lightroom Classic are trademarks of Adobe Inc. This project is an independent local automation bridge for users who already run Adobe Lightroom Classic. It is also not a generative image editor: it does not create, synthesize, replace, or AI-edit pixels.

What It Does

The goal is practical, non-generative photo workflow automation. This server does not create images and does not call image generation models. It is designed for Lightroom Classic catalog and workflow tasks such as:

• importing files or folders into a Lightroom Classic catalog;
• applying develop settings or preset-driven adjustments;
• exporting selected photos, collections, or batches to a chosen folder;
• updating metadata, collection membership, or workflow tracking fields;
• coordinating batch workflow steps that may take longer than a chat client request.

Current Status

Minimal usable workflow. The TypeScript MCP server, local HTTP bridge, job queue, single-process lock, structured logging, and Lightroom Classic Lua plugin are in place.

The included Lightroom Classic plugin polls the bridge, claims jobs, imports files into the active catalog, applies a small allowlisted set of non-destructive develop settings, lists and applies existing Lightroom develop presets, renders low-resolution JPEG previews of the current develop state, and exports selected/imported/collection photos as JPEGs. Metadata editing, Lightroom named export presets, recursive collection lookup, and larger batch workflow features are still future work.

For this repository's immediate self-use goal, "working" means this local Mac can install the plugin/server, import one real photo into Lightroom Classic, apply non-generative develop settings, export a JPEG to /Users/yopiesuryadi/Documents/leica, and verify the output file exists.

Why Async Jobs

Lightroom Classic operations can take longer than an MCP client timeout. Large imports, previews, exports, preset application, metadata writes, and batch workflows may run for minutes. If an MCP tool tries to do all of that inside one synchronous request, Claude, Codex, ChatGPT, or another MCP host can time out before Lightroom finishes.

This server uses an async job queue instead:

1. The MCP client calls a tool such as start_import or start_export.
2. The Node server stores a job and immediately returns a job_id.
3. The Lightroom Classic plugin polls the local bridge for queued work.
4. The plugin claims the job, performs Lightroom-side work, and reports progress.
5. The client polls job_status or list_jobs until the job succeeds or fails.

That design keeps the chat/MCP request short while allowing Lightroom Classic to continue the real desktop operation in the background.

Requirements

• macOS with Adobe Lightroom Classic installed.
• Node.js 20 or newer.
• An MCP-capable client, such as Claude Desktop, Codex, a ChatGPT MCP host, or another Model Context Protocol client.

Quickstart

git clone https://github.com/yopiesuryadi/lightroom-classic-mcp-server.git
cd lightroom-classic-mcp-server
npm install
npm run build
npm run install:plugin
npm run verify:plugin
npm start

The installer copies this repository's plugin to:

~/Library/Application Support/Adobe/Lightroom/Modules/LightroomClassicMCPServer.lrplugin

It deliberately uses a distinct folder name and preserves any older LightroomMCP.lrplugin folder. If an existing LightroomClassicMCPServer.lrplugin already looks like this project, the installer moves it to a timestamped backup before copying the current plugin; it refuses to replace unrelated folders unless you explicitly pass --force. Disable older duplicate plugin entries in Lightroom Classic if more than one appears in Plug-in Manager.

In Lightroom Classic, after installing or updating the plugin:

1. Open File > Plug-in Manager.
2. Confirm Lightroom Classic MCP Server Bridge is present and enabled.
3. If it is not listed, click Add and select the installed LightroomClassicMCPServer.lrplugin folder above.
4. Keep Lightroom Classic open so the plugin can poll the local bridge.

If Lightroom Classic was already running when you installed the plugin, quit and reopen Lightroom Classic, or manually add/reload the plugin in Plug-in Manager. Lightroom does not always load a newly copied .lrplugin folder until that happens.

Then add the MCP server command to your MCP client configuration and restart that client.

For a real local smoke test on this Mac, keep Lightroom Classic open with the plugin enabled, then run:

npm run build
npm run install:plugin
npm run smoke:local -- --input "/absolute/path/to/test-photo.jpg" --output-dir "/Users/yopiesuryadi/Documents/leica"

The smoke script starts the local bridge, queues import, edit, and export jobs, waits for the Lightroom Classic plugin to claim and finish them, and verifies that an exported file exists.

Install From This Repository

npm install
npm run build
npm run install:plugin
npm run verify:plugin

The built server entrypoint is:

dist/index.js

The source Lightroom Classic plugin folder in this repository is:

lightroom-classic-mcp-server.lrplugin

The installed Lightroom Classic plugin folder is:

~/Library/Application Support/Adobe/Lightroom/Modules/LightroomClassicMCPServer.lrplugin

Installer Commands

npm run install:lightroom-plugin
npm run install:plugin
npm run verify:plugin

install:lightroom-plugin is kept as a descriptive alias for install:plugin. The installer creates the Lightroom Modules folder if needed, backs up same-project installs, and copies the repository plugin into place without overwriting unrelated plugin folders. The verifier checks the installed plugin folder, expected toolkit identifier, Lightroom Classic process status, and the local bridge health endpoint if the MCP server is already running.

Configuration

Configuration is provided through environment variables.

LRC_MCP_BRIDGE_HOST=127.0.0.1
LRC_MCP_BRIDGE_PORT=58765
LRC_MCP_INPUT_DIR=~/Pictures
LRC_MCP_OUTPUT_DIR=~/Documents/leica
LRC_MCP_STATE_DIR=~/.lightroom-classic-mcp-server
LRC_MCP_LOG_FILE=~/.lightroom-classic-mcp-server/server.log
LRC_MCP_LOCK_FILE=~/.lightroom-classic-mcp-server/server.lock

Defaults:

• bridge host: 127.0.0.1
• bridge port: 58765
• input directory: ~/Pictures
• output directory: ~/Documents/leica
• state directory: ~/.lightroom-classic-mcp-server
• log file: ~/.lightroom-classic-mcp-server/server.log
• lock file: ~/.lightroom-classic-mcp-server/server.lock

MCP Config Examples

Use an absolute path to dist/index.js after running npm run build.

Claude Desktop

{
  "mcpServers": {
    "lightroom-classic": {
      "command": "node",
      "args": [
        "/Users/yopiesuryadi/Documents/leica/mcp/dist/index.js"
      ],
      "env": {
        "LRC_MCP_OUTPUT_DIR": "/Users/yopiesuryadi/Documents/leica"
      }
    }
  }
}

Codex

[mcp_servers.lightroom-classic]
command = "node"
args = ["/Users/yopiesuryadi/Documents/leica/mcp/dist/index.js"]

[mcp_servers.lightroom-classic.env]
LRC_MCP_OUTPUT_DIR = "/Users/yopiesuryadi/Documents/leica"

ChatGPT-Compatible MCP Host

Use the same stdio command shape if your ChatGPT or OpenAI-compatible MCP host supports local MCP servers:

{
  "name": "lightroom-classic",
  "command": "node",
  "args": [
    "/Users/yopiesuryadi/Documents/leica/mcp/dist/index.js"
  ],
  "env": {
    "LRC_MCP_BRIDGE_PORT": "58765"
  }
}

Exact file locations and schema names vary by host. The important parts are the node command, the absolute dist/index.js path, and any LRC_MCP_* environment variables you want to override.

MCP Tools

• start_import: queue a Lightroom Classic import and return a job_id.
• start_export: queue a Lightroom Classic export and return a job_id.
• start_edit_tracking: queue a non-destructive develop-setting workflow and return a job_id.
• get_develop_settings: queue a job that reads the target photo's full develop settings (including mask-based corrections) for AI inspection.
• start_adaptive_edit: queue an AI-authored adaptive (masked) edit; Lightroom computes Select Subject / Sky AI masks when the generated preset is applied. See the AI-Adaptive Editing Loop section for value-scale rules.
• get_preview: queue a fast, low-resolution sRGB JPEG render of the current develop state and return a job_id. job_result then returns the absolute preview path(s) and the JPEG as inline MCP image content for multimodal AI vision.
• list_develop_presets: queue a job that enumerates develop preset folders, preset names, and UUIDs.
• apply_develop_preset: queue a job that applies an existing develop preset (by name or UUID) non-destructively.
• job_status: inspect one job.
• job_result: inspect a completed job result without the full job envelope.
• job_error: inspect a failed job error without the full job envelope.
• list_jobs: list recent jobs.
• cancel_job: cancel a queued or running job.
• server_config: show effective non-secret server configuration.

AI-Adaptive Editing Loop

The preview and develop-setting tools support an AI-adaptive editing loop without changing Lightroom's non-destructive model:

1. Perceive: call get_preview, poll job_status, then inspect the absolute JPEG preview path or inline preview image from job_result.
2. Decide: compare the preview against the intended photographic direction and choose a small develop-setting or preset adjustment.
3. Act: call start_edit_tracking with allowlisted develop settings, or call apply_develop_preset with a UUID from list_develop_presets.
4. Verify: call get_preview again and compare the new current develop state before making another adjustment or exporting.

Beyond existing presets, start_adaptive_edit accepts raw MaskGroupBasedCorrections, so the model can author per-area corrections (subject / sky / background) with free values instead of a fixed preset matrix. Local values use XMP scale (LocalExposure2012 ±1.0 = ±4 stops); out-of-range values are silently dropped by Lightroom, and a new adaptive edit replaces all previous mask corrections.

For wiring this into an OpenClaw Telegram assistant, see docs/openclaw.md and the agent playbook example in docs/playbook-example.md.

Adaptive preset selection is still an experiment. Preset enumeration and application are available, but the model or operator is responsible for choosing appropriate presets, avoiding duplicate or ambiguous names by preferring UUIDs, and verifying the result with a preview before export.

Why get_preview Is Async

get_preview deliberately follows the existing async job pattern. The only channel into Lightroom Classic is the plugin's bridge poll loop (roughly every 2 seconds), and develop renders — especially of RAW files — can exceed an MCP client timeout. A synchronous tool would have to block the MCP request on both the poll interval and the render, so async is the safer choice here. The multimodal payoff still works: once the job succeeds, job_result attaches the rendered JPEG as inline MCP image content alongside the JSON result.

Preview behavior:

• Previews render through LrExportSession as sRGB JPEGs constrained to max_dimension (default 1200 px, capped at 2048) at JPEG quality (default 70).
• Preview files are written to ~/.lightroom-classic-mcp-server/previews/<job_id>/. The plugin deletes preview entries older than 24 hours on startup.
• One preview job renders at most 8 photos; result.truncated is true when the target contained more.
• job_result inlines up to 4 preview images (up to ~3.5 MB each); the absolute path(s) are always in the JSON result regardless.

Worked Example: Preview → Analyze → Edit → Verify

Assume one photo was just imported (target: "last_import"):

1. Call get_preview with { "target": "last_import" } and poll job_status until it succeeds.
2. Call job_result. The vision-capable client sees the preview image inline plus result.preview_path.
3. The AI observes, for example: underexposed midtones, a warm cast, flat contrast. It queues start_edit_tracking:

{
  "target": "last_import",
  "operation": "apply_develop_settings",
  "parameters": {
    "exposure": 0.4,
    "contrast": 12,
    "shadows": 18,
    "temperature": -300,
    "vibrance": 8,
    "vignette": -12,
    "grain_size": 25,
    "grain_frequency": 50
  }
}

4. Call get_preview again and compare. If highlights now clip, follow up with a smaller correction such as { "highlights": -20, "exposure": -0.1 } and re-verify.
5. For a black-and-white treatment, send { "black_white": true } (boolean), or apply a B&W preset via apply_develop_preset.
6. When the preview matches the intent, call start_export for the full-resolution output.

Supported develop-setting aliases include black_white/grayscale (boolean ConvertToGrayscale), vignette (PostCropVignetteAmount), grain/grain_amount, grain_size, and grain_frequency, in addition to the tone/color/crop keys listed in the start_edit_tracking tool description.

Adaptive Presets (Select Subject / Select Sky): Experiment Status

Lightroom Classic ships "Adaptive: Subject" and "Adaptive: Sky" preset groups that create AI masks when applied. Honest status: applying adaptive presets through this bridge is untested and may not compute masks headlessly. Adaptive presets do appear in LrApplication.developPresetFolders() on recent Lightroom Classic versions and photo:applyDevelopPreset accepts them, but the Select Subject/Select Sky mask computation runs in Lightroom's own ML pipeline, and Adobe does not document whether SDK-applied adaptive presets trigger it reliably outside the Develop module UI.

Manual experiment procedure (run once on your machine and record the outcome):

1. Import a test photo with a clear subject and visible sky, and select it in Lightroom.
2. Call list_develop_presets with { "name_filter": "adaptive" } and note the preset UUIDs (folders typically named Adaptive: Subject and Adaptive: Sky).
3. Call apply_develop_preset with one of those UUIDs and target: "selection".
4. Verify in Lightroom's Develop module: open the Masking panel and confirm a Subject or Sky mask was actually created with adjustments attached — not just a preset entry in the History panel.
5. Call get_preview before and after and compare renders visually; an adaptive preset that silently no-ops produces an unchanged preview.
6. If the mask is missing or empty, fall back to the manual step: select the photo in Lightroom, open the Presets panel in the Develop module, and click the adaptive preset there (the UI path always triggers mask computation). The rest of the loop — preview, verify, export — stays automated.

If the experiment succeeds on your Lightroom version, adaptive presets work inside the loop like any other preset. If it fails, treat adaptive presets as the one manual step in an otherwise automated loop.

Example Workflow

1. Ask your MCP client to import one image into Lightroom Classic.
2. The client calls start_import and receives a job_id.
3. Ask for the job status, or have the client poll job_status.
4. After import completion, queue a small edit job, for example:

{
  "target": "last_import",
  "operation": "apply_develop_settings",
  "parameters": {
    "exposure": 0.15,
    "contrast": 8,
    "vibrance": 10
  }
}

5. Queue an export job with selected_only: true, a collection, or no target after an import. With no target, the plugin exports the last photo(s) imported by this plugin session, then falls back to the current Lightroom selection. The default export folder is ~/Documents/leica.

For long imports or exports, prefer polling status over asking the client to wait silently.

Smoke Test

Use a single disposable image for the end-to-end test. The import is catalog-only and the develop settings are Lightroom non-destructive edits; the export writes a new JPEG and should not overwrite originals.

npm install
npm run build
npm run install:plugin
npm run verify:plugin
npm start

Then in Lightroom Classic, confirm the plugin is enabled in File > Plug-in Manager.

For the direct local harness:

npm run smoke:local -- --input "/absolute/path/to/test-image.jpg" --output-dir "/Users/yopiesuryadi/Documents/leica"

From an MCP client, run:

1. server_config
2. start_import with paths: ["/absolute/path/to/test-image.jpg"]
3. job_status until it succeeds
4. start_edit_tracking with target: "last_import", operation: "apply_develop_settings", and a small settings object
5. start_export with output_dir: "~/Documents/leica"
6. job_result to inspect the exported file path

Troubleshooting

The MCP client cannot start the server

• Run npm run build and confirm dist/index.js exists.
• Use an absolute path in your MCP config.
• Confirm Node.js 20 or newer with node --version.
• Check ~/.lightroom-classic-mcp-server/server.log.

Lightroom Classic does not appear to receive jobs

• Confirm the .lrplugin folder is installed in Lightroom Classic Plug-in Manager.
• Confirm Lightroom Classic is open.
• Confirm the server is listening on 127.0.0.1:58765, or update LRC_MCP_BRIDGE_PORT consistently.
• Look at ~/.lightroom-classic-mcp-server/server.log and the Lightroom plugin logs.

Startup fails because another server is running

The server uses a lock file to avoid multiple local bridge processes fighting for the same Lightroom Classic connection. Stop the older Node process, or inspect:

cat ~/.lightroom-classic-mcp-server/server.lock

If the process in the lock file is no longer running, a new server should replace the stale lock on startup.

Jobs stay queued

Queued jobs usually mean the Node MCP server is running but the Lightroom Classic plugin has not claimed work. Check that the plugin is installed, enabled, and configured for the same bridge host and port.

For local smoke testing, a timeout before the import job changes from queued means the Lightroom plugin is not polling the bridge. Restart Lightroom Classic or add/reload LightroomClassicMCPServer.lrplugin in Plug-in Manager, then rerun npm run smoke:local.

Jobs fail immediately

Check the returned error field with job_error. Common causes are a missing import path, no selected photo, a collection name that does not exist, unsupported source file format, Lightroom catalog write-access timeout, or an export destination that Lightroom cannot write.

Development

npm install
npm run build
npm run typecheck
npm run lint

Read docs/design.md for more detail on the timeout failure mode, async job queue, local bridge, and stale process strategy.