Lightroom Mcp

Lets Claude (and other AI assistants) talk to your Adobe Lightroom Classic photo catalog. Search photos, set ratings, edit develop settings, manage collections, import/export — all by chatting.

npm release

Works with: Claude Desktop, Claude Code, Codex CLI, Cursor, Windsurf, VS Code. Needs: Lightroom Classic on macOS or Windows. Nothing else — no programming required. Other languages: 繁體中文

Install (Claude Desktop — easiest, 3 steps)

This is the recommended path. Takes ~2 minutes, no terminal needed.

1. Download the installer

Go to the latest release page and download the file ending in .mcpb (it's near the top, called lightroom-mcp-<version>.mcpb).

2. Double-click the downloaded file

Claude Desktop opens automatically and asks: "Install Lightroom Classic extension?". Click Install.

Don't have Claude Desktop yet? Get it free from claude.com/download. It runs on Mac and Windows.

3. Turn on the plugin in Lightroom

1. Quit and reopen Lightroom Classic. (The plugin needs a restart to show up.)
2. In Lightroom, click File in the menu bar → Plug-in Manager.
3. In the left list, click Lightroom MCP.
4. On the right, click the Start Server button.
5. You should see "Server running" appear. Done!

Try it

Open Claude Desktop and type:

List all my Lightroom collections.

Claude will list every collection in your catalog.

Some other things to try:

• "Find all my 5-star photos from last summer."
• "Add the keyword 'portfolio' to the photos I have selected in Lightroom."
• "Apply the 'Vivid' develop preset to these photos."
• "Compare my approved 'John Warm v3' preset with the current candidate."
• "Create a versioned preset checkpoint from this representative photo and export it."
• "Export the selected photos to my Desktop as JPEGs at 2000px wide."

Install (other AI tools)

Already using Claude Code, Codex, Cursor, Windsurf, or VS Code? Pick your tool below. All paths still end with the Lightroom step from the section above — restart Lightroom and click Start Server in Plug-in Manager.

claude mcp add lightroom -- npx -y @mskalski/lightroom-mcp

codex mcp add lightroom -- npx -y @mskalski/lightroom-mcp

{
  "mcpServers": {
    "lightroom": {
      "command": "npx",
      "args": ["-y", "@mskalski/lightroom-mcp"]
    }
  }
}

npx -y @mskalski/lightroom-mcp install-plugin

Something not working?

1. Open Lightroom → File → Plug-in Manager → Lightroom MCP → Show Status. Both sockets should say connected: true. If not, click Start Server.
2. Make sure you fully quit and reopened Lightroom after install (Cmd+Q on Mac, Alt+F4 on Windows). "Reload Plug-in" alone is not enough.
3. See Troubleshooting below for specific errors.

Tools

Full schemas and parameter docs: server/src/list-tools-handler.ts.

Iterative preset workflow

Use a representative photo or virtual copy rather than a master edit:

1. Read an approved historical preset with get_develop_preset.
2. Apply bounded setting changes to the representative and export a Lightroom-rendered JPEG.
3. Create a uniquely named checkpoint such as John Warm v4 with create_develop_preset.
4. Compare it with the approved preset using compare_develop_presets.
5. Repeat the render/inspect cycle; export the accepted checkpoint with export_develop_preset.

create_develop_preset uses Adobe's plugin preset API. These checkpoints are intentionally hidden from the Develop panel and are listed with scope: "plugin". They are versioned instead of overwritten. export_develop_preset refuses existing destinations and preserves the backing file format Lightroom supplies. Built-in presets without a backing file cannot be exported.

Point curves

set_develop_settings accepts Lightroom's composite and per-channel point curve keys: ToneCurvePV2012, ToneCurvePV2012Red, ToneCurvePV2012Green, and ToneCurvePV2012Blue. Each value is a flat list of 2 to 32 input/output pairs. Values are integers from 0 to 255, inputs must be strictly increasing, and each curve must start at input 0 and end at input 255.

{
  "photo_id": "283615",
  "settings": {
    "ToneCurveName2012": "Custom",
    "ToneCurvePV2012": [0, 0, 40, 25, 128, 132, 220, 240, 255, 250],
    "ToneCurvePV2012Blue": [0, 0, 64, 58, 192, 198, 255, 255]
  }
}

How it works

┌─────────────┐    stdio    ┌──────────────────┐  TCP :58763 →   ┌──────────────────┐
│  AI client  │ ◄─────────► │   MCP server     │ ──────────────► │ Lightroom plugin │
│ (Claude/    │             │  (Node TCP)      │ ←────────────── │   (LrSocket)     │
│  Codex/...) │             └──────────────────┘   ← TCP :58764  └──────────────────┘
└─────────────┘                                                           │
                                                                          ▼
                                                                catalog:withReadAccessDo

Plugin binds two LrSocket servers on localhost (58763 request, 58764 response). Server connects as TCP client. Frame: line-delimited JSON, \n terminator. Auto-reconnect on both sides. Same dual-port pattern as MIDI2LR.

CLI reference

lightroom-mcp [stdio]            Run MCP over stdio (default)
lightroom-mcp install-plugin     Copy bundled plugin into Lightroom Modules folder
lightroom-mcp --help | --version

Env vars:

If you change ports on the server side, change them in Plug-in Manager → Lightroom MCP to match.

Security

The plugin generates a 256-bit token in ~/.config/lightroom-mcp/token on Start Server. The MCP server attaches it to every request. Localhost-only — no remote attack surface.

Develop

mise install                        # tools (node, bun, lua + luarocks, selene)
mise run install                    # npm ci
mise run build                      # tsc
mise run test                       # jest
mise run mcpb                       # build .mcpb bundle
mise run binary                     # build single-file binaries via Bun
mise run lua:lint                   # selene-lint the Lua plugin
mise run lua:test                   # busted specs for the Lua plugin

Repo layout:

• server/ — TypeScript MCP server (ESM, NodeNext).
• plugin/LightroomMCP.lrplugin/ — Lua plugin loaded by Lightroom Classic.
• mcpb/manifest.json — .mcpb bundle manifest.
• scripts/build-mcpb.mjs — pack the .mcpb.
• scripts/build-binary.mjs — Bun --compile per-target binaries.
• manual-test.mjs — direct TCP probe (bypasses MCP).

Adding a new tool

1. Add a new Handler*.lua under plugin/LightroomMCP.lrplugin/.
2. Register it in the DISPATCH table in PluginInfoProvider.lua.
3. Add a contract entry in server/src/tool-contracts.ts.
4. Declare any new LR globals in lightroom.yml (selene std).

Troubleshooting

• failed to open localhost:58763 after Reload Plug-in — old async task still owns the port. Quit Lightroom (Cmd+Q on macOS / Alt+F4 on Windows) and reopen.
• Plugin not connected — the server now self-restarts after a Reload Plug-in that tore down a running instance. If it's still stopped, click Start Server in Plug-in Manager; it reconnects within ~1s.
• Lightroom hangs on "performing shutdown tasks" when quitting, or warns that "a shutdown task for the plug-in became unresponsive" — fixed by removing the plugin's shutdown hooks. LrShutdownApp requires the script to return a table whose LrShutdownFunction calls Lightroom's doneFunction; without it Lightroom waits out a no-progress timeout on every quit, and even with it the shutdown dialog still costs about a second. The hooks bought nothing: Lightroom cancels the plugin's function context on quit, disable and reload, and that cleanup handler already closes both ports. Measured on macOS: 7.7 s with the hooks, 0.1 s without. If a future change needs work done at quit, re-register LrShutdownApp and return that table.
• Timeout errors — handler may be scanning a large catalog without filters; add rating, filename, keywords, or date filters to narrow.
• macOS "cannot be opened because the developer cannot be verified" (binary path) — xattr -d com.apple.quarantine /path/to/binary. Or right-click → Open the first time.
• Windows SmartScreen blocks the .exe — More info → Run anyway.

Logs:

The plugin resolves its log path via the OS (LrPathUtils), so on Windows with OneDrive-redirected Documents the file follows the redirect. The exact resolved path is shown as Log file: in Plug-in Manager → Show Status — use that if the table path above is empty.

License

MIT