Lightroom Classic 照片管理 MCP 服务器

Lightroom Classic MCP Server

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.

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.

The npm server requires Node.js 20 or later.

git clone https://github.com/Automaat/lightroom-mcp.git
claude --plugin-dir ./lightroom-mcp

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

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.

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.

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.

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

AI scores and reasons stay in the catalog's private plug-in metadata. They do not appear in the Metadata panel, searches, keywords, IPTC, XMP, or exports. set_ai_metadata leaves omitted fields unchanged; pass "" to clear a score or reason. get_ai_metadata omits unset fields and reports missing photo IDs. The initial provider schema is version 1: aiScore and aiReason are strings (the tools convert the score to and from an integer). Changes to these persistent field definitions require a schema version bump and migration; incompatible field changes also require a field version bump.

copy_develop_settings and apply_develop_preset accept dry_run: true to preview without writes or AI recomputation. Replies include per-setting totals and detail for at most five targets. detail_truncated flags omitted detail; missing_count and one-based missing_indices identify missing inputs when missing_truncated limits their path detail.

Preset previews compare only declared settings whose current values the SDK exposes. preview_scope states this limit, and unknown_current_totals counts unreadable values excluded from the diff. unknown_effects lists effects that remain unpredicted: SDK-generated values such as GrainSeed and preset bookkeeping. This preview does not predict the complete result of applying a preset.

First-pass cull workflow

Use vision as a first-pass reject filter for clear blur, closed eyes, missed focus and near-duplicates. Leave star ratings of the surviving photos to the user; thumbnails do not reliably distinguish a four-star photo from a five.

1. Collect photo IDs with search_photos. Read existing flags and labels with get_photo_metadata, and private reasons with get_ai_metadata.
2. Call get_photo_previews with at most 20 IDs at a time. The default minimum edge is 256 pixels; returned JPEGs have no edge over 2000 pixels and share an 8 MiB byte budget. Text maps each requested_id to its 1-based image_index. Inspect errors separately. Retry remaining_ids when complete is false.
3. Propose rejects with a reason per photo and show the list to the user before writing. Keep uncertain shots for review; do not reject them automatically.
4. For approved clear failures, call set_rating_and_flag with flag: "reject". Mark uncertain photos with set_color_label using label: "yellow" for “needs a look”. Preserve existing labels unless the user approves replacing them. Store each decision's reason with set_ai_metadata in its reason field (private plug-in field aiReason), never as keywords.
5. Verify flags and labels with get_photo_metadata, and reasons with get_ai_metadata. Undo a reject with set_rating_and_flag and flag: "none"; restore the previous label and reason when undoing the whole decision.

This workflow deletes nothing and removes no photos from the catalog.

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]
  }
}

Scope, write safety and limits

Your local Classic catalog

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 for the connection and Security for local access and authentication.

Safeguards when changing photos

• Deleting a collection with delete_collection keeps its photos in the catalog (collection handler).
• 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. They apply to those mask writes, not to every edit.
• Connections require the local token described in Security, checked by PluginInfoProvider.lua.

What Lightroom's plug-in SDK does not expose

The SDK is Adobe's interface for plug-ins. Its reference provides no documented calls for these operations:

• 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.
• Running an HDR or panorama merge; producing a print or book; creating or editing a slideshow. The SDK does support slideshow playback, but this server has no playback tool.
• Running Super Resolution or Raw Details through a documented call.
• 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.
• Folder create, move or delete operations in the catalog, or catalog open or close operations. Importing photos and managing collections are separate operations.
• Spot creation with the healing tools; Assisted Culling; Dust Removal; or Render to DNG.
• Running an HTTP server inside the plug-in. The connection uses the SDK's sockets instead; see How it works.

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. Copying develop-settings tables alone does not transfer those sidecar contents.

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.
• 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.
• 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