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.

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

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