Skip to content
Back to search

lightroom

Lightroom Classic tools and a RAW photo preset workflow.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Automaat/lightroom-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Automaat/lightroom-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/automaat--lightroom-mcp/badge.svg)](/listings/automaat--lightroom-mcp)

HTML

<a href="/listings/automaat--lightroom-mcp"><img src="/api/listings/automaat--lightroom-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

1. Download the installer

Go to the [latest release page](https://github.com/Automaat/lightroom-mcp/releases/latest) 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](https://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."*

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/plugin.json · Manifest · 11 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "lightroom",
  3. "version": "0.27.0",
  4. "description": "Lightroom Classic tools and a RAW photo preset workflow.",
  5. "author": {
  6. "name": "Marcin Skalski"
  7. },
  8. "homepage": "https://github.com/Automaat/lightroom-mcp#readme",
  9. "repository": "https://github.com/Automaat/lightroom-mcp",
  10. "license": "MIT"
  11. }
README.md · README · 451 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Lightroom Classic MCP Server
  2. 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.
  3. [![npm](https://img.shields.io/npm/v/@mskalski/lightroom-mcp.svg)](https://www.npmjs.com/package/@mskalski/lightroom-mcp)
  4. [![release](https://img.shields.io/github/v/release/Automaat/lightroom-mcp.svg)](https://github.com/Automaat/lightroom-mcp/releases/latest)
  5. [![Buy Me a Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-mskalski-FFDD00?logo=buymeacoffee&logoColor=black)](https://buymeacoffee.com/mskalski)
  6. > **Works with:** Claude Desktop, Claude Code, Codex CLI, Cursor, Windsurf, VS Code.
  7. > **Needs:** Lightroom Classic on macOS or Windows. Nothing else — no programming required.
  8. > **Other languages:** [繁體中文](README.zh-TW.md)
  9. ---
  10. ## Install (Claude Desktop — easiest, 3 steps)
  11. This is the recommended path. Takes ~2 minutes, no terminal needed.
  12. ### 1. Download the installer
  13. Go to the [latest release page](https://github.com/Automaat/lightroom-mcp/releases/latest) and download the file ending in **`.mcpb`** (it's near the top, called `lightroom-mcp-<version>.mcpb`).
  14. ### 2. Double-click the downloaded file
  15. Claude Desktop opens automatically and asks: *"Install Lightroom Classic extension?"*. Click **Install**.
  16. > Don't have Claude Desktop yet? Get it free from [claude.com/download](https://claude.com/download). It runs on Mac and Windows.
  17. ### 3. Turn on the plugin in Lightroom
  18. 1. **Quit and reopen Lightroom Classic.** (The plugin needs a restart to show up.)
  19. 2. In Lightroom, click **File** in the menu bar → **Plug-in Manager**.
  20. 3. In the left list, click **Lightroom MCP**.
  21. 4. On the right, click the **Start Server** button.
  22. 5. You should see "Server running" appear. Done!
  23. ### Try it
  24. Open Claude Desktop and type:
  25. > *List all my Lightroom collections.*
  26. Claude will list every collection in your catalog.
  27. Some other things to try:
  28. - *"Find all my 5-star photos from last summer."*
  29. - *"Add the keyword 'portfolio' to the photos I have selected in Lightroom."*
  30. - *"Apply the 'Vivid' develop preset to these photos."*
  31. - *"Compare my approved 'John Warm v3' preset with the current candidate."*
  32. - *"Create a versioned preset checkpoint from this representative photo and export it."*
  33. - *"Export the selected photos to my Desktop as JPEGs at 2000px wide."*
  34. ---
  35. ## Install (other AI tools)
  36. 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.
  37. The npm server requires Node.js 20 or later.
  38. <details>
  39. <summary><b>Claude Code</b></summary>
  40. Load the Claude plugin from a checkout to get the MCP server and the bundled skill together:
  41. ```bash
  42. git clone https://github.com/Automaat/lightroom-mcp.git
  43. claude --plugin-dir ./lightroom-mcp
  44. ```
  45. Use `/plugin` to check that `lightroom` is loaded. The skill is available as
  46. `/lightroom:raw-photo-lightroom-preset`. Node.js 20 or later is required: the
  47. plugin starts the published npm server with `npx`. That package includes the Lua bundle and
  48. installs it on first start when no Lightroom MCP plug-in is already installed.
  49. Restart Lightroom and click **Start Server** in Plug-in Manager.
  50. The same `.mcpb` file as Claude Desktop also works. To install only the MCP server:
  51. ```bash
  52. claude mcp add lightroom -- npx -y @mskalski/lightroom-mcp
  53. ```
  54. </details>
  55. <details>
  56. <summary><b>Codex CLI</b></summary>
  57. ```bash
  58. codex mcp add lightroom -- npx -y @mskalski/lightroom-mcp
  59. ```
  60. The Lightroom plugin installs itself the first time Codex talks to the server.
  61. </details>
  62. <details>
  63. <summary><b>Cursor / Windsurf / VS Code (Continue, Cline, Roo, ...)</b></summary>
  64. Open your client's MCP settings and add:
  65. ```json
  66. {
  67. "mcpServers": {
  68. "lightroom": {
  69. "command": "npx",
  70. "args": ["-y", "@mskalski/lightroom-mcp"]
  71. }
  72. }
  73. }
  74. ```
  75. The plugin installs itself the first time your client starts the server. If your client only starts the server on first tool call, you can install the plugin upfront:
  76. ```bash
  77. npx -y @mskalski/lightroom-mcp install-plugin
  78. ```
  79. </details>
  80. <details>
  81. <summary><b>No Node.js installed? Use the standalone binary</b></summary>
  82. 1. Download the right file from the [latest release](https://github.com/Automaat/lightroom-mcp/releases/latest):
  83. - **Mac (Apple Silicon, M1/M2/M3/M4):** `lightroom-mcp-darwin-arm64`
  84. - **Mac (Intel):** `lightroom-mcp-darwin-x64`
  85. - **Windows:** `lightroom-mcp-windows-x64.exe`
  86. 2. **macOS only** — make it runnable and bypass Gatekeeper (the binary isn't signed):
  87. ```bash
  88. chmod +x ~/Downloads/lightroom-mcp-darwin-arm64
  89. xattr -d com.apple.quarantine ~/Downloads/lightroom-mcp-darwin-arm64
  90. ```
  91. 3. Download `LightroomMCP-macos.lrplugin.zip` (or `LightroomMCP-windows.lrplugin.zip`) from the same release and extract it next to the binary, so the `LightroomMCP.lrplugin` folder sits beside it. Then install the Lightroom plugin:
  92. ```bash
  93. ~/Downloads/lightroom-mcp-darwin-arm64 install-plugin
  94. ```
  95. 4. Point your AI tool at the binary's full path. Example for Codex:
  96. ```bash
  97. codex mcp add lightroom -- /Users/you/Downloads/lightroom-mcp-darwin-arm64
  98. ```
  99. </details>
  100. <details>
  101. <summary><b>Install the Lightroom plugin manually (any client)</b></summary>
  102. If you'd rather drop the plugin in by hand:
  103. 1. Download the matching zip from the [latest release](https://github.com/Automaat/lightroom-mcp/releases/latest):
  104. - Mac: `LightroomMCP-macos.lrplugin.zip`
  105. - Windows: `LightroomMCP-windows.lrplugin.zip`
  106. 2. Unzip it. You get a folder called `LightroomMCP.lrplugin`.
  107. 3. Move that folder into Lightroom's Modules folder:
  108. - **Mac:** `~/Library/Application Support/Adobe/Lightroom/Modules/`
  109. - **Windows:** `%APPDATA%\Adobe\Lightroom\Modules\`
  110. - (If the `Modules` folder doesn't exist, create it.)
  111. 4. Restart Lightroom → **Plug-in Manager** → **Start Server**.
  112. </details>
  113. ---
  114. ## Something not working?
  115. 1. Open Lightroom → **File → Plug-in Manager → Lightroom MCP → Show Status**. Both sockets should say `connected: true`. If not, click **Start Server**.
  116. 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.
  117. 3. See [Troubleshooting](#troubleshooting) below for specific errors.
  118. ## Tools
  119. By default, the server exposes only core catalog and metadata tools. Set `LIGHTROOM_MCP_TOOLSETS` in your MCP client’s server environment to `develop`, `masks`, `develop,masks`, or `all` to add those tools. Core stays enabled. Restart the server after changing the setting; its tool list stays fixed for the session, and disabled tools cannot be called. In the desktop bundle, use **Enabled toolsets**.
  120. Set `LIGHTROOM_MCP_READ_ONLY` to `true` or `1` to hide write tools and refuse calls to them before they reach Lightroom, including when this server forwards through another bridge. The switch applies within the enabled toolsets. Exports (`export_photos`, `export_photo_metadata`, `export_develop_preset`) write files and are blocked. Read tools for masks and other Develop settings can briefly switch the module, photo or selected mask, then restore the previous view; they do not change photo data. Previews return image data in memory using Lightroom's preview cache. In the desktop bundle, enable **Read-only mode**. Restart the server after changing this setting.
  121. The Develop toolset includes presets, settings, snapshots, virtual copies, style summaries, Lens Blur, Denoise and Remove spots. The masks toolset includes all local mask tools. The table below lists every tool, including opt-in tools.
  122. | Tool | What it does |
  123. | --- | --- |
  124. | `search_photos` | Search by filename, keywords, rating, date, camera, lens, ISO, focal length (mm), flag, color label, edited status, file type or folder; filters intersect. |
  125. | `get_selected_photos` | Photos selected in Lightroom (or filmstrip). |
  126. | `get_photo_metadata` | Keywords (names and full paths), EXIF, GPS, IPTC location and copyright for one `photo_id` or up to 100 `photo_ids`. Batch results return `photos` in request order and `missing` identifiers. Pass `sections: ["developSettings"]` to include develop settings for each. |
  127. | `summarize_develop_settings` | Read-only medians and ranges of numeric Develop settings by camera and ISO (1–400, 401–1600, 1601–6400, 6401+, unknown). Rating ≥4 by default; optional exported filter intersects rating. Reads up to 200 photos; reports matched/scanned/truncated and settings omitted to keep each group under 6,000 characters. Excludes crop, perspective and white balance. |
  128. | `get_photo_preview` | JPEG preview of one photo (raw files too), optionally cropped to a rendered-frame region. `size: "cull"` requests 512 for culling; `"detail"` requests 1024 for inspecting details. Numeric sizes 64–2048 and the default 512 remain supported. |
  129. | `get_photo_previews` | Up to 20 ordered JPEG thumbnails with per-photo errors and partial timeout results. |
  130. | `get_photo_stats` | Rendered-preview luminance histogram, clipping fractions, mean luminance and sharpness for up to 20 photos; errors stay with each photo. |
  131. | `find_duplicate_groups` | Find near-duplicate and burst groups using JPEG dHash and raw capture time (up to 100 photos; defaults 5 s / 10 bits; 25 s partial-result budget) |
  132. | `set_gps` | Set the GPS position (decimal degrees) of photos. |
  133. | `set_location` | Set the IPTC location (sublocation, city, state, country, ISO code) of photos. |
  134. | `set_ai_metadata` | Store or clear private AI scores (0–100) and reasons (up to 1024 characters). |
  135. | `get_ai_metadata` | Read private AI scores and reasons for up to 1000 photos in one batch. |
  136. | `set_metadata` | Set title, caption, headline, creator and copyright fields of photos. |
  137. | `list_folders` | Catalog folders in tree order, with full paths and direct photo counts (paginated). |
  138. | `get_folder_photos` | Photos by full folder path, optionally including subfolders (paginated). |
  139. | `list_collections` | All collections and collection sets. |
  140. | `create_smart_collection` | Save `search_photos` filters as a smart collection; requires a filter and supports parent collection set paths. |
  141. | `create_collection` | New collection, optionally inside a collection set path (`Trips / 2026`); missing sets are created. |
  142. | `add_to_collection` | Add photos to a collection, by name or by its `list_collections` path. |
  143. | `get_collection_photos` | Photos in a collection, regular or smart (paginated). |
  144. | `remove_from_collection` | Remove photos from a collection (they stay in the catalog). |
  145. | `delete_collection` | Delete a collection (its photos stay in the catalog). |
  146. | `set_keywords` | Add or remove keywords on photos, by name or by hierarchy path (`Places\|Europe\|Paris`). |
  147. | `remove_keyword_subtree` | Detach a parent keyword and its descendants from selected photos, or explicitly from the whole catalog. Keyword nodes stay in the catalog. |
  148. | `list_keywords` | The keyword hierarchy as full paths, with synonyms. |
  149. | `rename_keyword` | Rename a keyword everywhere it is used. |
  150. | `undo_last_step` | Undo one step in Lightroom’s shared history with `confirm: true`; this includes user and other plug-in actions. |
  151. | `set_rating_and_flag` | Set a 0-5 star rating, a pick flag (`pick`, `reject`, `none`), or both in one write. |
  152. | `remove_photos_from_catalog` | Remove up to 100 specified photos from the catalog with `confirm: true` (Lightroom Classic 14.3+). Files stay on disk; catalog edits and metadata are lost. Selects in the photos' folders (All Photographs if one is not found), retrying for up to 30 s on large catalogs. Restores module, sources and surviving selection; Library remains in grid view. Include all virtual copies when removing a master. |
  153. | `set_color_label` | Set a red, yellow, green, blue or purple label, or clear it. |
  154. | `import_photos` | Import a file or folder into the catalog. A JPEG with a non-DNG raw file of exactly the same name stays the raw's sidecar unless `separate_jpegs` is set. Files already in the catalog are counted and left unchanged. |
  155. | `export_photos` | Export with format / quality / maximum width and height, or with a saved export preset. One export runs at a time. A photo with outdated AI settings can open Lightroom's AI Updates dialog, which blocks until dismissed. |
  156. | `list_export_presets` | List saved export presets and whether `export_photos` can use them. |
  157. | `export_photo_metadata` | Write metadata (incl. keyword paths) for many photos, or the selection, to a JSON file. |
  158. | `list_develop_presets` | Discover presets and plugin checkpoints by name (`query`) or exact `folder`, with `limit` (default 100) and `offset`. Returns `name`, `folder`, `scope`, `uuid`, total `count` and `has_more`; use `get_develop_preset` for `file`. |
  159. | `get_develop_preset` | Read settings and backing-file metadata for one exact preset. |
  160. | `compare_develop_presets` | Diff an approved historical preset against a candidate. |
  161. | `create_develop_preset` | Capture explicit settings from a photo as a versioned plugin checkpoint. |
  162. | `export_develop_preset` | Copy a custom/checkpoint preset backing file without overwriting. |
  163. | `apply_develop_preset` | Apply an exact preset by UUID or disambiguated name; recomputes AI masks per photo (LrC 13.3+). |
  164. | `copy_develop_settings` | Copy develop settings between photos; recomputes copied AI masks per photo (LrC 13.3+). |
  165. | `match_photo_style` | Match global style after a confirmed snapshot per target; preserves framing, white balance, lens corrections and local masks. Returns snapshot IDs for restoration. |
  166. | `set_develop_settings` | Write SDK setting key/values directly. |
  167. | `get_lens_blur` | Read Lens Blur state, controls, focal range and bokeh (LrC 13.3+, Process Version 3+); restores the Develop view. |
  168. | `set_lens_blur` | Set Lens Blur controls after enabling depth computation; validates runtime ranges and saved readback, then restores the view. |
  169. | `set_process_version` | Set photos to Version 1–6 with confirmation; refuses masked-photo downgrades and reports previous/actual versions. |
  170. | `list_develop_snapshots` | List a photo’s saved develop snapshots. |
  171. | `create_develop_snapshot` | Save current develop settings; set `replace` to update an existing name. |
  172. | `create_virtual_copies` | Create named virtual copies of up to 25 photos; return master and copy IDs and restore selection. |
  173. | `apply_develop_snapshot` | Restore a saved develop snapshot. |
  174. | `delete_develop_snapshot` | Delete one saved develop snapshot. |
  175. | `apply_auto_adjustments` | Apply Lightroom Auto Tone, Auto White Balance, or both, restoring the Develop view afterwards. |
  176. | `reset_develop_adjustments` | Reset all develop adjustments on up to 100 photos; requires `confirm: true`. Recover edits through Lightroom History. |
  177. | `apply_denoise` | Turn on AI Denoise at an amount (LrC 15+); drives the Develop module photo by photo. |
  178. | `list_spots` | List Remove spots with their indices and complete SDK parameters (LrC 14.1+) |
  179. | `update_spot` | Change a Heal spot's uppercase `params.Opacity` from 0 to 1 |
  180. | `delete_spot` | Delete one Remove spot by index with `confirm: true` |
  181. | `list_masks` | List a photo's masks with their ids, names, hidden state and component tools, and the stored range of each range mask tool, including the color sample's l, a and b (LrC 11+); briefly opens the photo in Develop. |
  182. | `create_gradient_mask` | Place a linear or radial gradient mask from normalized image coordinates, as a new mask or a component of one; optional `adjustments` sets a new mask's sliders in the same call (cannot combine with `mask_id`); guarded write, LrC 15.6 only; briefly opens the photo in Develop. |
  183. | `update_gradient_mask` | Move or reshape an existing linear or radial gradient by tool id; same guarded write. |
  184. | `create_brush_mask` | Paint a brush mask from strokes (points in normalized image coordinates, radius, flow, feather, density, erase), as a new mask or a component of one; optional `adjustments` sets a new mask's sliders in the same call (cannot combine with `mask_id`); guarded write, LrC 15.6 only; briefly opens the photo in Develop. |
  185. | `add_brush_strokes` | Paint more strokes into an existing brush by tool id; same guarded write. |
  186. | `create_range_mask` | Create a luminance, color or depth range mask (one color sample point given as Lightroom's own l, a and b, which `list_masks` reads from a color range made in Lightroom, not as sRGB, or copied from an existing color range with `copy_sample_from`; depth needs a photo with device depth such as an iPhone Portrait HEIC), as a new mask or an add/subtract component of one; optional `adjustments` sets a new mask's sliders in the same call (cannot combine with `mask_id`); guarded write, LrC 15.6 only; briefly opens the photo in Develop. |
  187. | `delete_masks` | With `photo_id`, delete masks or components by id, or all masks (LrC 11+); unknown ids delete nothing; briefly opens Develop. With only `photo_ids`, delete empty masks from up to 1000 photos without opening Develop or changing selection (LrC 14+). |
  188. | `set_mask_adjustments` | Change any subset of a mask's local sliders (`local_Exposure`, `local_Contrast`, ...) by mask id; out-of-range values are rejected before anything is written (LrC 11+); briefly opens the photo in Develop. |
  189. | `get_mask` | Read local adjustments, curves and Point Color in one Develop session; optional `kinds` selects `adjustments`, `curves` or `point_colors` (default all). Returns supported kinds and named errors for unsupported versions. |
  190. | `invert_mask` | Invert a mask by id, in place or as an inverted copy that keeps the original (LrC 11.4+); briefly opens the photo in Develop. |
  191. | `create_mask` | Create Subject/Sky/Background masks (LrC 11+) with optional adjustments, or People parts/Landscape categories (guarded LrC 15.6 / process 15.4) with `type: "people", parts: [...]` or `type: "landscape", categories: [...]`. Returns mask ids; missing AI parts leave no new masks. People/Landscape reject `adjustments`; use `set_mask_adjustments` afterwards. A single person cannot be chosen. |
  192. | `create_mask_batch` | Add the same Subject, Sky or Background mask with the same adjustments to up to 200 photos, each mask recomputed for its own photo; opens only the first photo in Develop; guarded write, LrC 15.6 only. |
  193. | `set_mask_curves` | Set a mask's local tone curve per channel (main, red, green, blue) by mask id (LrC 12.3+); briefly opens the photo in Develop. |
  194. | `edit_mask_point_colors` | Add, update, delete or clear a mask's local Point Color swatches by mask id (LrC 13.2+); briefly opens the photo in Develop. |
  195. | `combine_mask` | Add, subtract or intersect a Subject, Sky or Background component on an existing mask by id and get the component's id (LrC 11+); briefly opens the photo in Develop. |
  196. Full schemas and parameter docs: [`server/src/list-tools-handler.ts`](server/src/list-tools-handler.ts).
  197. AI scores and reasons stay in the catalog's private plug-in metadata. They do
  198. not appear in the Metadata panel, searches, keywords, IPTC, XMP, or exports.
  199. `set_ai_metadata` leaves omitted fields unchanged; pass `""` to clear a score
  200. or reason. `get_ai_metadata` omits unset fields and reports missing photo IDs.
  201. The initial provider schema is version 1: `aiScore` and `aiReason` are strings
  202. (the tools convert the score to and from an integer). Changes to these
  203. persistent field definitions require a schema version bump and migration;
  204. incompatible field changes also require a field version bump.
  205. `copy_develop_settings` and `apply_develop_preset` accept `dry_run: true` to
  206. preview without writes or AI recomputation. Replies include per-setting totals
  207. and detail for at most five targets. `detail_truncated` flags omitted detail;
  208. `missing_count` and one-based `missing_indices` identify missing inputs when
  209. `missing_truncated` limits their path detail.
  210. Preset previews compare only declared settings whose current values the SDK
  211. exposes. `preview_scope` states this limit, and `unknown_current_totals` counts
  212. unreadable values excluded from the diff. `unknown_effects` lists effects that
  213. remain unpredicted: SDK-generated values such as `GrainSeed` and preset
  214. bookkeeping. This preview does not predict the complete result of applying a
  215. preset.
  216. ### First-pass cull workflow
  217. Use vision as a first-pass reject filter for clear blur, closed eyes, missed
  218. focus and near-duplicates. Leave star ratings of the surviving photos to the
  219. user; thumbnails do not reliably distinguish a four-star photo from a five.
  220. 1. Collect photo IDs with `search_photos`. Read existing flags and labels with
  221. `get_photo_metadata`, and private reasons with `get_ai_metadata`.
  222. 2. Call `get_photo_previews` with at most 20 IDs at a time. The default minimum
  223. edge is 256 pixels; returned JPEGs have no edge over 2000 pixels and share an
  224. 8 MiB byte budget. Text maps each `requested_id` to its 1-based `image_index`.
  225. Inspect errors separately. Retry `remaining_ids` when `complete` is false.
  226. 3. Propose rejects with a reason per photo and show the list to the user before
  227. writing. Keep uncertain shots for review; do not reject them automatically.
  228. 4. For approved clear failures, call `set_rating_and_flag` with `flag: "reject"`. Mark
  229. uncertain photos with `set_color_label` using `label: "yellow"` for
  230. “needs a look”. Preserve existing labels unless the user approves replacing
  231. them. Store each decision's reason with `set_ai_metadata` in its `reason`
  232. field (private plug-in field `aiReason`), never as keywords.
  233. 5. Verify flags and labels with `get_photo_metadata`, and reasons with
  234. `get_ai_metadata`. Undo a reject with `set_rating_and_flag` and `flag: "none"`;
  235. restore the previous label and reason when undoing the whole decision.
  236. This workflow deletes nothing and removes no photos from the catalog.
  237. ### Iterative preset workflow
  238. Use a representative photo or virtual copy rather than a master edit:
  239. 1. Read an approved historical preset with `get_develop_preset`.
  240. 2. Apply bounded setting changes to the representative and export a Lightroom-rendered JPEG.
  241. 3. Create a uniquely named checkpoint such as `John Warm v4` with `create_develop_preset`.
  242. 4. Compare it with the approved preset using `compare_develop_presets`.
  243. 5. Repeat the render/inspect cycle; export the accepted checkpoint with `export_develop_preset`.
  244. `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.
  245. ### Point curves
  246. `set_develop_settings` accepts Lightroom's composite and per-channel point curve
  247. keys: `ToneCurvePV2012`, `ToneCurvePV2012Red`, `ToneCurvePV2012Green`, and
  248. `ToneCurvePV2012Blue`. Each value is a flat list of 2 to 32 input/output pairs.
  249. Values are integers from 0 to 255, inputs must be strictly increasing, and each
  250. curve must start at input 0 and end at input 255.
  251. ```json
  252. {
  253. "photo_id": "283615",
  254. "settings": {
  255. "ToneCurveName2012": "Custom",
  256. "ToneCurvePV2012": [0, 0, 40, 25, 128, 132, 220, 240, 255, 250],
  257. "ToneCurvePV2012Blue": [0, 0, 64, 58, 192, 198, 255, 255]
  258. }
  259. }
  260. ```
  261. ## Scope, write safety and limits
  262. ### Your local Classic catalog
  263. This server works with the catalog open in Lightroom Classic on your computer through a Lightroom plug-in. Use it to organize photos, adjust edits and masks, and export Lightroom-rendered images. Lightroom Classic must be running. See [How it works](#how-it-works) for the connection and [Security](#security) for local access and authentication.
  264. ### Safeguards when changing photos
  265. - Deleting a collection with `delete_collection` keeps its photos in the catalog ([collection handler](plugin/LightroomMCP.lrplugin/HandlerCollections.lua)).
  266. - Mask tools that write Lightroom's undocumented mask format check the Lightroom version, the photo's process version and the format of existing masks before writing. They read the result back and attempt to restore the previous masks if it differs; an unconfirmed restoration is reported as an error. These checks live in [GuardedMaskWrite.lua](plugin/LightroomMCP.lrplugin/GuardedMaskWrite.lua). They apply to those mask writes, not to every edit.
  267. - Connections require the local token described in [Security](#security), checked by [PluginInfoProvider.lua](plugin/LightroomMCP.lrplugin/PluginInfoProvider.lua).
  268. ### What Lightroom's plug-in SDK does not expose
  269. The SDK is Adobe's interface for plug-ins. Its [reference](https://lrc.mcor.dev/) provides no documented calls for these operations:
  270. - Reading raw sensor histograms, individual pixel data or detected face regions. `get_photo_stats` measures the rendered JPEG preview; `get_photo_preview` returns that image for visual inspection.
  271. - Running an HDR or panorama merge; producing a print or book; creating or editing a slideshow. The SDK does support [slideshow playback](https://lrc.mcor.dev/modules/LrSlideshow.html), but this server has no playback tool.
  272. - Running Super Resolution or Raw Details through a documented call.
  273. - Stack create or unstack operations on photos already in the catalog, or auto-stacking. The SDK's import operation can add a new photo to a stack.
  274. - Folder create, move or delete operations in the catalog, or catalog open or close operations. Importing photos and managing collections are separate operations.
  275. - Spot creation with the healing tools; Assisted Culling; Dust Removal; or Render to DNG.
  276. - Running an HTTP server inside the plug-in. The connection uses the SDK's sockets instead; see [How it works](#how-it-works).
  277. Pixel-based AI edits have another limit: copying a table of develop settings does not copy their generated image data. Since Lightroom Classic 15.0, Lightroom stores heavy edits, including AI edits, in [`.acr` sidecars when saving metadata to files](https://helpx.adobe.com/lightroom-classic/help/create-xmp-acr-files.html). Copying develop-settings tables alone does not transfer those sidecar contents.
  278. ## How it works
  279. ```
  280. ┌─────────────┐ stdio ┌──────────────────┐ TCP :58763 → ┌──────────────────┐
  281. │ AI client │ ◄─────────► │ MCP server │ ──────────────► │ Lightroom plugin │
  282. │ (Claude/ │ │ (Node TCP) │ ←────────────── │ (LrSocket) │
  283. │ Codex/...) │ └──────────────────┘ ← TCP :58764 └──────────────────┘
  284. └─────────────┘ │
  285. ▼
  286. catalog:withReadAccessDo
  287. ```
  288. 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.
  289. ## CLI reference
  290. ```
  291. lightroom-mcp [stdio] Run MCP over stdio (default)
  292. lightroom-mcp install-plugin Copy bundled plugin into Lightroom Modules folder
  293. lightroom-mcp --help | --version
  294. ```
  295. Env vars:
  296. | Var | Default | Purpose |
  297. | --- | --- | --- |
  298. | `LIGHTROOM_MCP_REQUEST_PORT` | `58763` | Plugin request port. |
  299. | `LIGHTROOM_MCP_RESPONSE_PORT` | `58764` | Plugin response port. |
  300. | `LIGHTROOM_MCP_TOOLSETS` | `core` | Comma-separated `core`, `develop`, `masks`, or `all`; core is always enabled. |
  301. | `LIGHTROOM_MCP_READ_ONLY` | `false` | `true` or `1` hides and refuses write tools; `false`, `0`, unset or empty disables the switch. Values are case-sensitive and surrounding whitespace is ignored. Invalid values fail startup. |
  302. | `LIGHTROOM_MCP_TOKEN_PATH` | `~/.config/lightroom-mcp/token` | Auth token file. |
  303. If you change ports on the server side, change them in **Plug-in Manager → Lightroom MCP** to match.
  304. ## Security
  305. 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.
  306. ## Develop
  307. ```bash
  308. mise install # tools (node, bun, lua + luarocks, selene)
  309. mise run install # npm ci
  310. mise run build # tsc
  311. mise run test # jest
  312. mise run mcpb # build .mcpb bundle
  313. mise run binary # build single-file binaries via Bun
  314. mise run lua:lint # selene-lint the Lua plugin
  315. mise run lua:test # busted specs for the Lua plugin
  316. ```
  317. Repo layout:
  318. - `server/` — TypeScript MCP server (ESM, NodeNext).
  319. - `plugin/LightroomMCP.lrplugin/` — Lua plugin loaded by Lightroom Classic.
  320. - `mcpb/manifest.json` — `.mcpb` bundle manifest.
  321. - `scripts/build-mcpb.mjs` — pack the .mcpb.
  322. - `scripts/build-binary.mjs` — Bun `--compile` per-target binaries.
  323. - `manual-test.mjs` — direct TCP probe (bypasses MCP).
  324. ## Adding a new tool
  325. 1. Add a new `Handler*.lua` under `plugin/LightroomMCP.lrplugin/`.
  326. 2. Register it in the `DISPATCH` table in `PluginInfoProvider.lua`.
  327. 3. Add a contract entry in `server/src/tool-contracts.ts`.
  328. 4. Declare any new LR globals in `lightroom.yml` (selene std).
  329. ## Troubleshooting
  330. - **`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.
  331. - **Server not running right after Lightroom starts** — Lightroom Classic runs the plugin's start-up script only once its window is first brought to the front, even with `LrForceInitPlugin`. Seen on LrC 15.6 macOS: launched in the background (`open -g`), the plugin did nothing for 90 s and started the moment the window was activated. A Lightroom opened hidden (a login item set to hide, `open -g`, a script) therefore has no server until you switch to it once. The plugin log shows `Plugin initialized, auto-start on` when the script runs.
  332. - **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.
  333. - **Lightroom never finishes quitting while an MCP client is connected** — fixed by registering an `LrShutdownApp` script (`PluginShutdown.lua`) that stops the server loop before Lightroom closes the listeners. Without it the loop took the closed request listener for a catalog switch and rebound it; the still-running client reconnected at once and kept Lightroom in quit until the client exited. `LrShutdownApp` requires the script to return a table whose `LrShutdownFunction` calls Lightroom's `doneFunction`; the script does that at once, so the shutdown dialog stays at most a brief flash.
  334. - **Timeout errors** — handler may be scanning a large catalog without filters; add `rating`, `filename`, `keywords`, or date filters to narrow.
  335. - **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.
  336. - **Windows SmartScreen blocks the .exe** — More info → Run anyway.
  337. Logs:
  338. | Component | macOS | Windows |
  339. | --- | --- | --- |
  340. | Plugin | `~/Documents/LrClassicLogs/LightroomMCP.log` | `%USERPROFILE%\Documents\LrClassicLogs\LightroomMCP.log` |
  341. | Claude Desktop | `~/Library/Logs/Claude/mcp*.log` | `%APPDATA%\Claude\Logs\mcp*.log` |
  342. The plugin resolves its log path via the OS (`LrPathUtils`), so on Windows with
  343. OneDrive-redirected Documents the file follows the redirect. The exact resolved
  344. path is shown as **Log file:** in Plug-in Manager → **Show Status** — use that if
  345. the table path above is empty.
  346. ## License
  347. MIT

Version history

  • v0.27.011/7/2026

  • v0.26.010/28/2026

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.