Skip to main content

lightroom-mcp

Control Adobe Lightroom Classic from the command line, and expose the same operations to AI agents through an MCP server.

  • Search and inspect photos, collections and keywords (reads the catalog directly; Lightroom can be closed)
  • Organize: ratings, flags, color labels, keywords, text metadata, collections
  • Develop: read and apply settings, presets, copy settings, virtual copies
  • Export through Lightroom's own renderer
  • Plugins: list, install, uninstall, reload; restart Lightroom

macOS only. Built against Lightroom Classic 11 (SDK 11).

How it works

lightroom-mcp (Typer) ─┐
                       ├─> core functions ─┬─> catalog.py   read-only SQLite on the .lrcat
lightroom-mcp mcp ─────┘                   ├─> bridge.py    JSON lines over a localhost socket, replies as files
(FastMCP, stdio)                           └─> plugins/app  files in Modules/, osascript to quit
                                                  │
                              LightroomBridge.lrplugin (Lua, runs inside Lightroom)

Reads go straight to the catalog file, opened read-only. Anything that changes Lightroom goes through a small Lua plugin that runs inside Lightroom and uses the official SDK, so every change is a normal undoable Lightroom action. The catalog file is never written to directly.

Setup

Install the lightroom-mcp command:

uv tool install lightroom-mcp

(or pipx install lightroom-mcp). Then install the bridge plugin:

lightroom-mcp plugins bridge-install --restart

This copies the plugin into ~/Library/Application Support/Adobe/Lightroom/Modules/ and restarts Lightroom so it loads. Check it with:

lightroom-mcp status

After upgrading lightroom-mcp, run bridge-install again so the plugin matches.

Usage

Photos are addressed by catalog id (the id column from photos search) or with --selected for the current Lightroom selection. Add --json before the command for machine-readable output.

lightroom-mcp photos search --rating ">=3" --camera "EOS" --after 2026-01-01
lightroom-mcp photos show 153 --develop
lightroom-mcp photos selected

lightroom-mcp organize rate 4 153 194
lightroom-mcp organize flag picked --selected
lightroom-mcp organize label red 153
lightroom-mcp organize set-metadata 153 -f title="Studio test" -f caption="First roll"
lightroom-mcp keywords add "film,studio" 153 194
lightroom-mcp collections create "Best Of"
lightroom-mcp collections add "Best Of" 153 194

lightroom-mcp develop get 153 --keys Exposure2012,Temperature,Tint
lightroom-mcp develop set Exposure2012=0.5 Contrast2012=10 --id 153
lightroom-mcp develop copy 153 194 229 --keys Temperature,Tint
lightroom-mcp develop presets
lightroom-mcp develop apply-preset "My Preset" --selected
lightroom-mcp develop virtual-copy 153

lightroom-mcp export 153 194 --to ~/Desktop/out --format jpeg --quality 85 --long-edge 2048

lightroom-mcp plugins list
lightroom-mcp plugins install ~/dev/MyPlugin.lrplugin --link --restart
lightroom-mcp plugins uninstall MyPlugin --restart
lightroom-mcp plugins reload
lightroom-mcp plugins extras
lightroom-mcp app restart

MCP server

lightroom-mcp mcp runs a FastMCP server over stdio. To add it to Claude Code:

claude mcp add lightroom -- uvx lightroom-mcp mcp

Or in a JSON MCP config (Claude Desktop and others):

{
  "mcpServers": {
    "lightroom": {
      "command": "uvx",
      "args": ["lightroom-mcp", "mcp"]
    }
  }
}

Tools mirror the CLI: search_photos, get_photo, selected_photos, set_rating, set_flag, set_color_label, add_keywords, set_metadata, create_collection, add_to_collection, get_develop_settings, apply_develop_settings, apply_develop_preset, copy_develop_settings, create_virtual_copies, export_photos, list_plugins, install_plugin, uninstall_plugin, reload_plugin, restart_lightroom and more. Read-only tools are annotated as such; tools that overwrite edits, delete plugins or restart Lightroom are marked destructive.

Plugin management limits

The Lightroom SDK has no API for installing, removing or reloading plugins, or for one plugin to run another's menu commands. So:

  • install / uninstall copy into or delete from Lightroom's user Modules folder and take effect on restart. Plugins added through Plug-in Manager are listed but must be removed there.
  • reload restarts the bridge plugin in place (its server and command handlers) without restarting Lightroom. Any other plugin is reloaded by restarting Lightroom (--restart).
  • plugins extras lists every plugin's Plug-in Extras commands; run-extra can only run the bridge's own.
  • osascript is used only to ask Lightroom to quit. No UI scripting, no Accessibility permission.

Configuration

Variable Purpose
LIGHTROOM_CATALOG Path to the .lrcat to read. Default: ~/Pictures/Lightroom/Lightroom Catalog.lrcat
LIGHTROOM_BRIDGE_PORT Port the bridge plugin listens on. Default: 58763

Security

The bridge listens on localhost only and has no authentication: any local process can send it commands while Lightroom is open. Don't install it on a shared machine.

Development

git clone https://github.com/0xB0Bdev/lightroom-mcp.git
cd lightroom-mcp
uv sync
uv run pytest

Run the CLI from the checkout with uv run lightroom-mcp …. Install the bridge with --link to work on the Lua handlers in place; lightroom-mcp plugins reload picks up edits to any of the plugin's Lua files without restarting Lightroom.

License

MIT

Metadata

Release files for lightroom-mcp 0.1.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for lightroom-mcp 0.1.3
File Size Uploaded Provenance Actions
lightroom_mcp-0.1.3.tar.gz 37.7 kB With provenance Details for lightroom_mcp-0.1.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for lightroom-mcp 0.1.3
File Interpreter ABI Platform Actions
lightroom_mcp-0.1.3-py3-none-any.whl Python 3 none any Details for lightroom_mcp-0.1.3-py3-none-any.whl

Total release size: 85.3 kB

Release files / lightroom_mcp-0.1.3.tar.gz

Download URL lightroom_mcp-0.1.3.tar.gz
Size 37.7 kB
Tags Source
SHA-256 checksum
How to use checksums
89d54064923323ba850089c5c84b34ee2ab112ab9a6bdf35cd1805f3af9e6235
BLAKE2b-256 checksum
How to use checksums
e36ad13690d95dc9d9a797ad87d4c695ef9884ea6aaea4f7aea0296d397b2d5f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Release files / lightroom_mcp-0.1.3-py3-none-any.whl

Download URL lightroom_mcp-0.1.3-py3-none-any.whl
Size 47.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d606b55a8909c0ebd295ad28a3ef1cfc0b0f220dc21977989501b5de7e2a447b
BLAKE2b-256 checksum
How to use checksums
7c17873ccf1579dd1ad6a6b90e4a04640829c45936ffff43abcb33ef3fac3dcd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Security for lightroom-mcp 0.1.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for lightroom_mcp-0.1.3.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.3 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page