LightroomForge · 影调锻造厂

简体中文 · English

An MCP server that gives AI agents full control of Adobe Lightroom Classic — catalog, develop engine, and masks.
一个让 AI 智能体直接操控 Adobe Lightroom Classic 的 MCP 服务：目录检索、全套显影参数、几何蒙版与 AI 蒙版、预设、预览与导出。

名字由来：Forge（锻造）——影调不是套出来的，是一档一档锻出来的。LightroomForge = 在 Lightroom 里锻造影调的工作台。

目录

• 这是什么

• 能力总览

• 配合 skill 的自动化修图

• 系统架构

• 环境要求

• 安装

• 快速上手

• 工具参考

• 蒙版体系详解

• 已知限制

• 故障排查

• 开发与热更新

• 目录结构

• 致谢与许可

Related MCP server: Lightroom MCP Elite

这是什么

Lightroom Classic 本身不提供任何外部 API。LightroomForge 由两部分组成：

1. Lightroom Lua 插件（lightroom-python-bridge.lrdevplugin）——运行在 Lightroom 内部，通过目录级直写（applyDevelopSettings）绕过 UI 控制显影参数与蒙版；

2. Python MCP 服务（mcp_server/）——把插件能力包装成 167 个 MCP 工具，任何支持 MCP 的 AI 客户端（WorkBuddy、Claude Desktop、Cursor 等）都能直接调用。

关键设计：能力在插件里，MCP 只是传输层。即使 MCP 客户端出问题，直接用 lightroom_sdk 也能连上插件干活。

能力总览

特色能力：

• 蒙版免手拖：线性/径向/画笔蒙版的几何坐标可直写，配合 zero/full 两点式定位；

• AI 蒙版：天空/主体/背景/物体/人物可直接创建；山脉/水面/人物等景观元素可通过 develop_create_image_mask 直接写入（详见蒙版体系）；

• 本地参数自动换算：蒙版调整参数直接传 UI 值（-100..100、曝光 EV），插件自动转换为目录量纲；

• 写入门哨兵：LR 写锁拥挤时会静默丢弃写入——本项目所有写操作都会检测并显式报错，绝不假成功。

配合 skill 的自动化修图（探索中）

本项目提供的是能力层（MCP）——能读、能写、能建蒙版、能出预览。至于「怎么调」——诊断素材、定风格、编排蒙版、量化自检——属于 skill 的方法论层。两层合起来，可以做到一定程度的全自动修图。

下面就是作者本人跑出来的结果（北疆雪山湖，一张 RAW）：

原片（上）vs AI 全自动调色（下）：天空压暗青、雪山去朦胧加锐、地面降曝、草地生成斜射光斑——全程零人工操作，参数由 AI 看片后自己决定。

MCP 直写落进 Lightroom 的蒙版组：天空暗青、雪山去朦胧加锐、地面压暗、草地光斑、山体受光、水面（water-bridge-test）——全部由 AI 创建，没有手拖一次。

需要坦白的是：作者的 skill 目前仍在探索阶段，这套全自动流程的最终效果离「出片」还有相当距离——上图基本就是当前水平（甚至不算这张片子的最好版本），请把它当能力验证而不是作品来看。

所以这里只是抛砖引玉：能力层已经铺好、坑也踩平了，方法论那半张图，欢迎各位用自己的审美和方案去补。如果你跑出了更好的结果，非常欢迎回来分享。

系统架构

┌─────────────────┐   MCP(stdio)   ┌──────────────────────┐
│  AI 客户端       │ ◄────────────► │  Python MCP Server    │
│ (WorkBuddy 等)  │                │  mcp_server/ (167 工具)│
└─────────────────┘                └──────────┬───────────┘
                                              │ JSON over TCP（双 socket）
                                              │ 端口见 lightroom_ports.txt
                                   ┌──────────▼───────────┐
                                   │   Lightroom Lua 插件   │
                                   │  单/双 socket + 路由   │
                                   └──────────┬───────────┘
                                              │ LrApplication / LrDevelopController
                                   ┌──────────▼───────────┐
                                   │  Lightroom Classic     │
                                   │  目录库 .lrcat          │
                                   └──────────────────────┘

为什么是双 socket：Lightroom 的 LrSocket 单向，发和收必须分开两条连接；MCP 层用 LRBRIDGE_PORT_FILE（或自动发现）定位端口文件。

环境要求

安装

1. 安装 Lightroom 插件

Lightroom → 文件 → 增效工具管理器 → 添加，选择 lightroom-python-bridge.lrdevplugin 文件夹。

或手动复制到：

• Windows：%APPDATA%\Adobe\Lightroom\Modules\lightroom-python-bridge.lrdevplugin

• macOS：~/Library/Application Support/Adobe/Lightroom/Modules/lightroom-python-bridge.lrdevplugin

2. 启动桥接

插件默认 autoStart=true：加载后自动启动、自动注册全部命令、零操作。

备用入口（自动启动失败时）：文件 → 增效工具额外功能 → Start Python Bridge。

启动成功后插件目录内会生成 lightroom_ports.txt（两行端口号，send/recv）。

3. 安装 Python 依赖

cd LightroomForge-MCP
python -m venv .venv
# Windows
.venv\Scripts\python -m pip install -r requirements.txt
# macOS/Linux
.venv/bin/python -m pip install -r requirements.txt

4. 配置 MCP 客户端

在客户端的 MCP 配置里加入（路径换成本机实际路径）：

{
  "mcpServers": {
    "lightroom": {
      "command": "D:/LightroomForge-MCP/.venv/Scripts/python.exe",
      "args": ["D:/LightroomForge-MCP/run_mcp.py"],
      "env": {
        "LRBRIDGE_PORT_FILE": "D:/LightroomForge-MCP/lightroom_ports.txt"
      }
    }
  }
}

LRBRIDGE_PORT_FILE 可省略——客户端会自动在「项目根目录 / Lightroom Modules 插件目录」里找最新的端口文件。

5. 验证

system_status

返回 connected: true 即打通。若失败，看故障排查。

快速上手

典型会话（AI 视角）：

1. catalog_search_photos(filename="DSC01445")        → 找到照片 ID
2. catalog_open_in_develop(photo_ids=["140279"])     → 切到修改照片模块
3. develop_auto_tone()                               → 自动定调
4. develop_set_parameters({"Exposure2012": 0.3, "Contrast2012": 25, "Saturation": -12})
5. develop_create_linear_mask(...)                   → 天空/地面渐变
6. preview_generate(photo_id="140279", size=1024)    → 拉预览看效果
7. histogram_analyze_current()                       → 量化自检
8. catalog_export_photos(photo_ids=[...], output_dir="/out", format="jpeg")

用 SDK 直连（不经过 MCP，适合脚本与调试）：

import asyncio
from lightroom_sdk import LightroomClient

async def main():
    c = LightroomClient()
    await c.connect()
    r = await c.execute_command("develop.getSettings", {"photoId": "140279"}, timeout=30)
    print(r)
    await c.disconnect()

asyncio.run(main())

lightroom_run_command(command, params) 可以把任意已注册的 Lua 命令直接透传——插件新增能力永远不需要等 Python 侧更新。

工具参考

目录 catalog_*

显影 develop_*（133 个）

按类别（全部支持批量读写，develop_batch_get_settings / develop_batch_apply_settings）：

蒙版 develop_*mask*

预设 / 预览 / 直方图

蒙版体系详解

三种蒙版

景观元素子类型 ID（实测）

量纲约定（重要）

蒙版局部参数直接传 UI 值，插件自动换算：

• 曝光：EV（如 0.5），内部存 EV/4

• 其余（对比/清晰度/去朦胧/锐化/色温/饱和…）：-100..100，内部存 /100

直接传目录量纲会被 LR 静默丢弃——这是本项目最常踩的坑，已在 _build_correction_group 统一处理。

AI 蒙版的位图机制

AI 蒙版的位图不在设置文本里，而是存在 <目录名>.lrcat-data（RocksDB blob），通过 MaskDigest 引用：

• 带 digest 的组（从既有蒙版克隆 InputDigest/MaskDigest/FullMaskSize/Origin/ReferencePoint/WholeImageArea）→ 即刻有效；

• 无 digest 的裸组 → 组存在、面板可见，但 LR 不会自动计算位图（渲染、切蒙版工具、直写都不触发）；

• 真正的「新照片自动算」走 预设套用路径：自适应预设（XMP）里不带 MaskDigest，套用时会触发 AI 重算。preset_apply 已打通这条路。

注意：LR 只在启动时扫描 Develop Presets 目录，新写入的预设需重启 LR 才能被 preset_list 看到。

蒙版组的读-改-写铁律

getDevelopSettings() 不返回 MaskGroupBasedCorrections。任何「读出全部组 → 追加 → 写回」的流程，读必须来自目录库：

# 正确姿势（示意）：从 .lrcat 解析现有组，再整表写回
groups = parse_groups_from_catalog(catalog_path, photo_id)   # SQLite 读取 + 解析 Lua 表文本
groups.append(new_group)
await client.execute_command("develop.createImageMask",
                             {"subCategoryId": 50002, "existingGroups": groups})

examples/create_ai_image_mask.py 里有可用的解析器实现。

已知限制

故障排查

桥接连不上

1. 看端口文件是否存在且新鲜：插件目录 / 项目根目录的 lightroom_ports.txt

2. 检查端口是否被占：netstat -ano | findstr <端口>（历史坑：迅雷等下载器抢占端口）

3. 重载插件：增效工具管理器 → 重载增效工具（桥会自动重启）

4. 插件日志：%LOCALAPPDATA%\Adobe\Lightroom\Logs\LrClassicLogs\LightroomPythonBridge.log

写入"成功"但目录没变化

写锁被僵尸任务侵占。本项目所有写 handler 都带 executed 哨兵，会报 write gate skipped——看到这个错误，重载增效工具；仍不行就重启 LR。

蒙版没效果

• 确认量纲：UI 值不是目录值；

• 确认 MaskActive=true、组 CorrectionActive=true；

• AI 蒙版确认 MaskDigest 存在（目录库查 Adobe_imageDevelopSettings.text）。

开发与热更新

# 启动
python -m mcp_server.main          # 推荐
python run_mcp.py                  # 等价入口

两部分的热更新策略：

新增 Lua 命令只需两步：把 handler 写进对应模块 + 调 system.reloadModules——路由器有动态分发兜底（module.fn 约定从模块表找函数），不需要改注册表。

调试：Lua 侧 logger:info(...) → 插件日志；Python 侧 logging → 客户端 stderr；直连调试用 lightroom_sdk（见快速上手）。

更深入的架构约定与踩坑记录见 docs/DEVELOPMENT.md。

目录结构

LightroomForge-MCP/
├── README.md                中文（默认）
├── README.en.md             英文
├── assets/                  README 配图（前后对比、蒙版面板）
├── LICENSE                  Apache-2.0
├── NOTICE                   上游项目致谢
├── requirements.txt
├── run_mcp.py               MCP 服务入口
├── mcp_server/              167 个 MCP 工具
│   ├── main.py              组合入口 + 能力清单
│   ├── servers/             system / catalog / develop / preview / presets
│   ├── shared/              重连与命令执行
│   └── middleware/          错误映射
├── lightroom_sdk/           TCP 客户端 SDK（可独立使用）
├── lightroom-python-bridge.lrdevplugin/
│   ├── PluginInit.lua       注册表 + 热更新 + 自动启动
│   ├── CommandRouter.lua    分发（含动态兜底）
│   ├── SimpleSocketBridge.lua  双 socket 主循环
│   ├── MessageProtocol.lua  JSON 编解码
│   ├── CatalogModule.lua    目录 / 导入导出 / 切模块
│   ├── DevelopModule.lua    显影 + 蒙版（含 AI 图像蒙版）
│   ├── PreviewModule.lua    预览渲染
│   └── PresetModule.lua     预设
├── docs/
│   ├── API_REFERENCE.md
│   ├── API_DEVELOP_REFERENCE.md
│   └── DEVELOPMENT.md
└── examples/
    ├── preview.py
    └── create_ai_image_mask.py

致谢与许可

本项目是合并版，吸收了两个上游开源项目的设计与代码：

• lightroom-python-bridge（noopz）——Lua 插件骨架、双 socket 桥、MCP 服务框架；

• @mskalski/lightroom-mcp——导入/导出/预设管理的 API 使用方式与任务模型经验。

合并、修复与新增（2026-10）：任务模型适配、JSON 编解码修复、蒙版量纲换算、AI 图像蒙版直写、预设管理、热更新、写门哨兵、UUID 修复。

License: Apache-2.0（见 LICENSE），上手即用，改动请保留版权声明。