Lightroom Classic MCP

Agentic professional photo editing for Adobe Lightroom Classic on macOS.

This project combines a Lightroom Classic plugin bundle and a Python MCP server so Codex, Claude, and other MCP clients can operate Lightroom through Lightroom itself. The goal is simple: expose serious editing and catalog workflows without touching the catalog database directly.

This project is not affiliated with or endorsed by Adobe.

Install In 2 Minutes

If you want to use this with Codex or Claude, start here:

git clone https://github.com/4xiomdev/lightroom-classic-mcp.git
cd lightroom-classic-mcp
./scripts/install_for_ai.sh --client both

That one command:

• installs the Lightroom plugin bundle
• bootstraps the Python runtime
• registers the MCP server with Codex
• registers the MCP server with Claude

By default, the registered MCP command expects Lightroom to already be open. That avoids surprising app launches when Codex or Claude probes the server.

Homebrew install:

brew tap 4xiomdev/tap
brew install lightroom-classic-mcp
lightroom-classic-mcp-install --client both

If you prefer the old behavior where the MCP command opens Lightroom for you, use --auto-launch during install.

Use With Codex

Fast path:

./scripts/install_for_ai.sh --client codex

Manual Codex registration:

codex mcp add lightroom-classic -- bash -lc 'cd "/absolute/path/to/lightroom-classic-mcp" && ./scripts/start_managed_server.sh'

Use With Claude

Fast path:

./scripts/install_for_ai.sh --client claude

Manual Claude registration:

claude mcp add -s local lightroom-classic -- bash -lc 'cd "/absolute/path/to/lightroom-classic-mcp" && ./scripts/start_managed_server.sh'

More detail: docs/CLIENT_SETUP.md

Launch Behavior

The MCP wrapper does not auto-open Lightroom by default.

That is intentional. During clean-install testing, automatic app launch turned out to be noisy and surprising, especially when clients probe MCP servers in the background.

Default behavior:

• open Lightroom yourself
• then let Codex or Claude connect through MCP

If you want the MCP wrapper to launch Lightroom for you, install with:

./scripts/install_for_ai.sh --client both --auto-launch

Why This Exists

Lightroom Classic is still the center of a lot of real photo workflows, but it is hard to automate safely from external tools. This project gives an AI agent a controlled way to:

• inspect the current selection
• read and write metadata
• read and write Develop settings
• apply grouped looks and presets
• work with masks, collections, snapshots, exports, and virtual copies

The key design choice is that Lightroom still performs the actual work. The Python side acts as a bridge and validation layer, not as a catalog editor.

What This Feels Like

This is meant to feel like a professional photo editing operator for Lightroom Classic:

• inspect selected photos and catalog state
• inspect the original file directly from the Lightroom-provided path
• apply structured edit changes safely
• read and write Develop settings through Lightroom
• automate repetitive editing workflows
• stay local, deterministic, and compatible with real Lightroom usage

Inspection-First Workflow

The preferred workflow is:

1. ask Lightroom for the active photo or current selection
2. use the returned absolute file path to inspect the original image directly
3. decide your edit
4. apply Lightroom changes through MCP
5. export only if you need a rendered before/after or final output

New inspection tools:

• get_active_photo_file
• get_selected_photo_files

These are read-only MCP tools that return Lightroom metadata plus a normalized inspection payload:

• absolute file path
• local ID
• filename
• dimensions when available
• file existence / readability / inspectability flags
• basic file metadata like suffix, MIME type, and size when readable

Example Agent Prompts

Inspect the active image before editing:

Use get_active_photo_file, inspect the image at the returned path, then tell me what edit you would make before changing anything in Lightroom.

Snapshot first, then make a targeted edit:

Use get_active_photo_file to inspect the active image, create a Lightroom snapshot, then lift the subject slightly without blowing out highlights.

Use export only for verification:

Inspect the active image from its original file path, make the edit in Lightroom, then export a verification JPEG so we can compare before and after.

Restore if needed:

If the edit is not an improvement, restore the most recent Lightroom snapshot instead of trying to manually undo each slider.

Who This Is For

• photographers building agentic editing workflows around Lightroom Classic
• creative technologists connecting Codex or Claude to a real editing environment
• developers who want a local-first Lightroom MCP server that is installable and scriptable

How It Works

lightroom-classic-mcp is split into three parts:

1. a Lightroom plugin bundle in plugin/LightroomMCPCustom.lrplugin
2. a localhost socket bridge implemented inside Lightroom
3. a Python MCP server in src/lightroom_mcp_custom/

When the plugin starts, it opens localhost sockets and writes bridge metadata to /tmp/lightroom_mcp_custom_ports.json. The managed server launcher waits for that handshake and then starts the MCP server over stdio.

More detail: docs/ARCHITECTURE.md

Requirements

• macOS
• Adobe Lightroom Classic installed locally
• Python 3.10+
• An MCP client that can launch a local command

What You Get

• non-destructive Lightroom SDK-driven edits
• localhost-only bridge
• validation before Develop writes
• a one-command managed startup path
• a repo layout that keeps the Lightroom plugin and MCP server together
• direct file-path inspection helpers for active and selected photos

Repository Layout

• plugin/LightroomMCPCustom.lrplugin/ - Lightroom plugin bundle
• src/lightroom_mcp_custom/ - Python MCP server and bridge client
• scripts/install_plugin.sh - installs the plugin bundle into Lightroom's plugin folders
• scripts/start_managed_server.sh - recommended launcher for daily use
• scripts/run_server.sh - starts the MCP server directly
• scripts/smoke_bridge.py - verifies local bridge connectivity
• scripts/print_mcp_config.sh - prints an MCP config snippet for the current checkout path
• scripts/package_release.sh - builds source and plugin zip bundles in dist/

Install From A Release

If you downloaded a release zip instead of cloning the repo:

1. Unzip it anywhere on your Mac.
2. Run ./scripts/install_for_ai.sh --client both.

If you only want one client, use --client codex or --client claude.

Quick Start

1. Clone the repo anywhere on your Mac.

git clone <your-repo-url>
cd lightroom-classic-mcp

2. Run the guided installer.

./scripts/install_for_ai.sh --client both

3. If Lightroom does not already have the plugin loaded:

• Open File -> Plug-in Manager
• Add or enable ~/Library/Application Support/Adobe/Lightroom/Modules/LightroomMCPCustom.lrdevplugin

4. Verify the bridge.

PYTHONPATH=src python3 scripts/smoke_bridge.py

5. Print the MCP config snippet for your actual checkout path.

./scripts/print_mcp_config.sh

6. Use the managed server command in your MCP client.

./scripts/start_managed_server.sh

Recommended MCP Client Command

The printed config from scripts/print_mcp_config.sh is the easiest way to avoid path mistakes. The generated command uses your current absolute checkout path and launches the managed server:

./scripts/start_managed_server.sh

That script:

1. refreshes the plugin install
2. checks for a live Lightroom bridge
3. waits for the bridge port file
4. launches the MCP server

Why The Managed Launcher Matters

The managed launcher is the reason this project behaves reliably on a normal local Lightroom setup:

• it refreshes the plugin bundle before each run unless you opt out
• it fails fast if Lightroom is closed, unless you explicitly enable auto-launch
• it waits for Lightroom to publish the bridge port file
• it only starts the MCP server after that handshake exists

That preserves the same startup model this project uses successfully in local development.

Configuration

Optional environment variables:

• LIGHTROOM_SKIP_INSTALL=1 skips plugin reinstall
• LIGHTROOM_AUTO_LAUNCH=1 opens Lightroom automatically when the managed server starts
• LIGHTROOM_FORCE_RESTART=1 force restarts Lightroom before launch
• LIGHTROOM_WAIT_SECONDS=180 changes the bridge wait timeout
• LIGHTROOM_ROOT=/custom/path overrides the default Lightroom support directory during install
• LIGHTROOM_WRITE_PREFS=0 skips the automatic Lightroom plugin-loader preference update
• LIGHTROOM_VENV_DIR=/custom/venv/path overrides the Python runtime location
• LIGHTROOM_BOOTSTRAP_PYTHON=python3.12 chooses the Python executable used for venv creation

Safety And Scope

• Python-side validation clamps or rejects invalid Develop settings before they reach Lightroom
• Lightroom writes happen through the Lightroom SDK, not direct .lrcat mutation
• The bridge is localhost-only
• This project is intentionally local-first and currently macOS-only
• Snapshot-first is the recommended non-destructive edit pattern, but it is documentation guidance rather than a forced wrapper mode

Testing

Unit tests run with plain pytest.

Live integration tests require a running Lightroom bridge and are opt-in:

LIGHTROOM_RUN_INTEGRATION=1 pytest -q

Without that flag, the integration suite is skipped by default so CI and fresh contributors do not need Lightroom installed just to contribute.

Packaging GitHub Releases

To build release bundles:

./scripts/package_release.sh

That creates:

• a source zip for the repo
• a plugin zip containing LightroomMCPCustom.lrplugin

Homebrew release notes and packaging guidance live in docs/DISTRIBUTION.md.

• Lightroom Classic only
• macOS only
• requires the plugin bundle to be installed locally
• live integration tests cannot run in generic CI because they need Lightroom