Scouter MCP server
Commit Nov 11, 2026Allows an AI client to edit photos in darktable through conversational commands and manage photo libraries via the Lua API.
Also known as pratikgh0se/scouter
- Stars
- 0
- Tools
- 10
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 11, 2026
- License
- MIT
What is Scouter MCP?
Scouter allows an AI client to edit photos in darktable through conversational commands and manage photo libraries via the Lua API. It exposes 10 tools, such as view_photos, rate_photos, import_batch.
Summary generated from the project's README
About Scouter MCP server
Photographers can manage their darktable workflows through natural language by using Scouter to bridge the gap between an AI client and their photo editing software. By connecting to a running darktable instance via a Lua plugin, the server allows an agent to perform complex edits like increasing contrast or warmth using conversational commands. The system ensures accuracy by reading XMP sidecar files back to confirm that every change was successfully applied to the image.
Beyond simple edits, the server provides extensive library management and camera ingest capabilities. Developers can use tools to browse photo libraries by rating, apply specific darktable styles, or batch import images from a camera using libgphoto2. It also supports headless workflows, such as extracting JPEG previews from raw files or exporting images to various formats using darktable-cli in an isolated configuration to avoid database locks. This setup is designed for users who want to automate repetitive organization tasks or use an AI to drive precise photographic adjustments.
What you can do with it
- 1Conversational photo editingAsk the AI to adjust the visual tone of an open photo using simple descriptive phrases.
- 2Automated camera ingestDirect the AI to detect a connected camera and import all photos into a specific destination directory.
- 3Headless preview extractionHave the AI extract small thumbnail previews from a directory of raw files for rapid review.
Written from the project's README. Every use case is checked against a quote from it.
Scouter MCP tools 10
Detected from the READMEview_photosrate_photosimport_batchlist_stylesapply_presetimport_from_cameraextract_previewsapply_ratings_batchopen_in_darktableexport_images
Configuration
SCOUTER_HOST_TESTSSCOUTER_JOB
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablepratikgh0se/scouter is public and reachablegithub.com/pratikgh0se/scouter ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-11github.com/pratikgh0se/scouter ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model10 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubScouter
MCP server for editing photos in darktable by conversation. Ask for "warmer" or "more contrast" and Scouter makes the edit in your running darktable, then reads the XMP sidecar back to confirm it landed.
Quick start
Tested on macOS with darktable 5.4.1 (darktable-cli on PATH) and Python 3.10+.
pip install 'git+https://github.com/pratikgh0se/scouter@v0.3.0'
scouter setup # installs the darktable Lua plugin, prints the `claude mcp add` line
# restart darktable and open a photo in the darkroom, then:
scouter setup --check # exits 0 when everything is ready
Run the claude mcp add line that scouter setup printed (or add the JSON it prints to any MCP client), then ask something like "make it a bit warmer and add contrast".
What it does
- Edits the photo open in darktable's darkroom through darktable's Lua API. Each change is one history item you can see and undo.
- Turns plain phrases ("warmer", "a touch brighter", "punchier") into fixed parameter steps (
darkroom_say), or sets exact values (darkroom_set). - Confirms every write by reading the XMP sidecar back. If darktable writes an older history over it, Scouter refuses the write and restores the sidecar.
- Renders previews with
darktable-cliin an isolated config, so the agent can look at the result (scout_preview). - Never writes to darktable's
library.db.
Known limits are listed under Honest limits.
Scouter is a fork of w1ne/darktable-mcp (MIT). The original darktable-mcp tools are documented below and still ship in this package as the darktable-mcp command.
darktable-mcp tools (from upstream)
A Model Context Protocol (MCP) server that exposes darktable operations to MCP clients (Claude Desktop, Claude Code, etc.). The AI lives in the client; this server drives darktable.
Tools
Library operations (require darktable-mcp install-plugin and an open darktable session):
view_photos(filter?, rating_min?, limit?)— Browse the library by filename substring and minimum rating. Returns id, filename, absolute file path, and rating per match — the path drops straight intoexport_images'sphoto_ids.rate_photos(photo_ids, rating)— Apply -1..5 star ratings (-1 = reject, 0 = unrated).import_batch(source_path, recursive?)— Register a folder as a film roll.recursive=trueis honoured in Lua by walking the tree and importing each directory, so it works regardless of darktable'srecurse_directoriespreference.recursive=falsecannot stop darktable recursing, so the response says so (recursive_honoured: false) rather than claiming a mode it did not deliver. If darktable's background scan has not settled when the plugin answers, the count is reported as a floor, not a total.list_styles()— Enumerate installed darktable styles (presets), returning name + description per entry.apply_preset(photo_ids, preset_name)— Apply a named darktable style to one or more photos. Uselist_stylesfirst to discover exact names.
Camera ingest (headless):
-
import_from_camera(destination?, camera_port?, timeout_seconds?)— Detect a camera via libgphoto2 and copy photos to a local directory. Auto-merges hybrid setups (one card on PTP, the other mounted as USB Mass-Storage) into a single import — Nikon DSLRs in particular show up that way and the previous behavior silently halved the import.Files land one subdirectory per camera folder or card, prefixed with the camera's identity — never flat:
<destination>/Nikon_D850_sn_30014567_store_00010001_DCIM_100NCD80/DSC_0001.NEF <destination>/Nikon_D850_sn_30014567_store_00020001_DCIM_100NCD80/DSC_0001.NEF # same name, different photo <destination>/Canon_EOS_R6_EOS_DIGITAL_100EOSR6/IMG_0001.CR3 <destination>/.import.logCamera filenames repeat across folders, across the two cards of a dual-slot body, and across bodies importing into the same destination — and the default destination
~/Pictures/import-YYYY-MM-DD/is shared by every import on the same day. The old flat layout combined with gphoto2's--skip-existingsilently dropped those duplicates; correctness no longer rests on that flag, which now only ever sees files the same run just wrote into its own private staging directory. Import the destination recursively.The serial number is read once per camera via
gphoto2 --get-config serialnumberand omitted when the camera doesn't report one. On both paths a file that would collide with a different photo already on disk is written alongside it asIMG_0001-2.CR3and reported — never overwritten; sameness is judged on size plus the first and last 8 KB, and is only ever used to authorise a skip.Two bodies of the same model that report no serial share a destination subdirectory, and both bodies' photos are kept there. The PTP path downloads into a private staging area and, before skipping files the destination appears to already hold, re-checks a bounded sample of them against the bytes on disk — a second body fails that check and its folder is fetched in full. Re-running stays cheap: a body with a serial transfers nothing it already delivered, and one without transfers at most 3 files per folder. Any file the card lists that doesn't reach the destination is reported by name.
Residual limit: that sample is bounded at 3 files per folder, so a second body whose sampled files are byte-identical to the first body's — in a folder holding more than 3 candidates — is still taken to be the same body. Folders with 3 or fewer candidates are checked exhaustively.
timeout_secondsis an overall budget for one camera, shared across all its folders — not a per-folder timeout. Skipped files are counted and reported, and a post-flight shortfall (fewer files on disk than the camera said it held) is surfaced as a prominent!! INCOMPLETE IMPORTblock, because that is the moment before someone formats the card.
Vision-rating workflow (headless, file-based — no library required, needs [vision] extra):
extract_previews(source_dir, output_dir?, max_dim?, thumb_dim?, overwrite?, max_workers?)— Pull auto-rotated JPEG previews + small thumbs out of raws (NEF/CR2/ARW/DNG/...), with an EXIF summary per file. Per-file details (paths, EXIF, errors) land in<output_dir>/.extract_previews.jsonl; the tool response keeps only counts and the side-file path so 700+ NEFs don't overflow the agent's context. The scan is recursive and the output tree mirrors the source tree, so same-named raws in different subdirectories get distinct previews — read the path from each item rather than assuming<output_dir>/<stem>.jpg. Decoding runs on a thread pool (max_workers, defaultmin(8, cpu_count)).apply_ratings_batch(source_dir, ratings, log?, force?)— Write XMPxmp:Ratingsidecars for a{stem: rating}batch + an append-onlyratings.jsonllog. Keys may be a bare stem or a source-relative path; a bare stem that matches raws in more than one subdirectory is rejected as ambiguous rather than resolved by guesswork.open_in_darktable(source_dir, rating?, rating_min?, rating_max?)— Launch the GUI on a folder. Auto-registers as a film roll; pre-applies any rating filter (exact, ≥, ≤, or inner range) viadt.gui.libs.collect.filter.
Behaviour worth knowing
Existing XMP sidecars are patched, never replaced. apply_ratings_batch rewrites only the rating value and leaves every other byte intact, so darktable edit history survives. A sidecar with no recognisable rating is skipped with an error instead of being overwritten. force=True opts into wholesale replacement and discards edit history — it exists for the "reset these sidecars" case and nothing else.
Ratings for photos darktable already knows need one manual step. darktable prefers its own library.db over the sidecar for images already in the library, so writing a sidecar changes nothing on screen. When this is detected the summary warns and names the affected files; run selected image(s) → read sidecar files in the lighttable to pull them in.
open_in_darktable no longer claims a launch it didn't get. An already-open darktable is the normal state when the bridge-backed library tools are in use, and it holds the lock on library.db. What darktable then does is platform-dependent, and neither branch is a launch:
| behaviour | reported as | |
|---|---|---|
| Linux (session D-Bus present) | hands the folder to the running instance, child exits 0 | handed_off_to_running_instance: true — look at the open window |
| macOS (no session D-Bus) | handoff fails on a GLib assertion and the child hangs forever | launched: false with the reason; the hung child is killed |
The tool used to report a phantom pid in both cases. Detection reads what darktable says, not whether the process is alive — on macOS it stays alive indefinitely, so liveness proves nothing. Verified against darktable 5.6.0.
Export:
-
export_images(photo_ids, output_path, format, quality?, max_width?, max_height?)— Export to JPEG/PNG/TIFF viadarktable-cli. Runs in an isolated config dir under$XDG_CACHE_HOME/darktable-mcp/cli-config/, so exports work even when the GUI is open (nodatabase is lockedrace against the user's~/.config/darktable/library.db). Files export in parallel, and the output isstated afterwards — darktable-cli can exit 0 without writing anything, which used to be reported as success. Per-file results land in<output_path>/.export_images.jsonl; the tool response is bounded — counts, side-file path, and the first error if any.Output names are de-collided: two inputs with the same stem from different folders no longer overwrite each other, so read the real path from the
outputfield rather than assuming<stem>.<format>. Note darktable-cli picks the extension itself —jpegwrites.jpgandtiffwrites.tif. Each parallel worker gets its own config dir, because concurrentdarktable-cliprocesses sharing one contend for the samelibrary.dband one of them silently writes nothing.Sidecar caveat: because the config dir is isolated from the GUI's, exports read develop settings from XMP sidecars only. If darktable's write sidecar file for each image preference is off, files export without their edits and darktable-cli still reports success.
Design rules
Use only the official darktable APIs: darktable-cli for export, the Lua API for everything else. No direct library.db reads or writes. Tools that return data to the AI must be headless; the GUI may launch only when the tool's purpose is to show the human something.
Why some tools are parked
darktable-cli doesn't load the user's library and darktable --lua brings up the full GUI, so there's no headless one-shot path for library reads/writes. Iteration 2 (spec: docs/superpowers/specs/2026-04-27-ipc-bridge-mvp-design.md) shipped a long-running Lua plugin loaded into the user's interactive darktable session, with a file-based JSON RPC bridge. The library tools (view_photos, rate_photos, import_batch, list_styles, apply_preset) all ride on it.
adjust_exposure was retired during iteration 3 — see docs/superpowers/specs/2026-04-28-iter3-design.md. The darktable Lua API in 9.6.0 exposes neither image.modules nor image.history, and dt.gui.action requires an active darkroom view (single-image, GUI-driven). The realistic future paths (pre-created .dtstyle exposure presets + apply_preset, or darktable-cli --style for export-only) are workable but not "set +N EV from Lua" tools.
Installation
Not on PyPI yet — install from the repository:
pip install 'git+https://github.com/pratikgh0se/scouter'
# Optional: vision-rating workflow extras
pip install 'darktable-mcp[vision] @ git+https://github.com/pratikgh0se/scouter'
# Install the Lua plugin into ~/.config/darktable/, then restart darktable
darktable-mcp install-plugin
You also need darktable (with darktable-cli) on PATH. The [vision] extra pulls in rawpy, Pillow, and pyexiv2, which need system libraw and libexiv2.
Configuration
Add to your Claude Desktop config:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
{
"mcpServers": {
"darktable": {
"command": "darktable-mcp"
}
}
}
Vision-rating workflow
When darktable's library doesn't yet know about your shoot — typically straight off a card — you can rate by vision before any import:
extract_previewswrites auto-rotated JPEGs and an EXIF summary so the client can iterate efficiently.- The client reads previews, decides ratings, and calls
apply_ratings_batchto write XMP sidecars next to the raws. open_in_darktablelaunches the GUI with the folder as a film roll, lighttable filtered to the rating range you want.
No SQLite poking, no half-imported state, no GUI launch until step 3.
Requirements
- Python 3.10+ (the floor comes from
mcp, which requires 3.10) - darktable 4.0+ (with
darktable-clionPATH) - An MCP-compatible client (Claude Desktop, Claude Code, etc.)
- Linux, or macOS for the parts that don't need
gphoto2. The plugin installer writes to~/.config/darktable/, which is where darktable keeps its config on Linux and macOS but not on Windows —import_from_cameraalso needsgphoto2, which has no Windows build.
The MCP SDK is pinned to mcp>=2,<3. Tools are registered through the mcp 2.x low-level Server(on_list_tools=…, on_call_tool=…) handlers; the 1.x decorators this server used before do not exist in 2.x, so mcp 1.x cannot run this code.
The low-level API is deliberate. The high-level MCPServer derives each inputSchema from the handler signature, which cannot express additionalProperties: {type: integer, minimum: -1, maximum: 5} — the rating bounds on apply_ratings_batch silently disappear — and it injects a title into every property. The tool schemas here are handwritten and pinned by a golden-snapshot test, because their descriptions are what the calling model reads to decide behaviour.
Scouter (live darktable editing core)
Scouter is the fork's own product: a live editing core for the running
darktable, driven by conversation or by script. It sits on top of this repo's
bridge (the Lua plugin and the file-spool JSON-RPC client), which is unchanged
and still serves the original darktable-mcp tools.
Three layers over one core, with the same verb names, arguments and result shape in all three:
| Layer | How you use it |
|---|---|
| Python | from scouter.core import darkroom; darkroom.set_param(module="exposure", param="exposure", value=1.2) |
| CLI | scouter darkroom set exposure exposure 1.2 — one JSON object on stdout, one exit code per error class |
| MCP | the scouter-mcp server, tools darkroom_set, scout_stats, … (handwritten schemas, golden-snapshot tested) |
Add the MCP server to your client's config alongside (or instead of) darktable:
{
"mcpServers": {
"scouter": {
"command": "scouter-mcp"
}
}
}
Setup
uv sync --extra dev # or: python3 -m venv .venv && .venv/bin/pip install -e '.[dev]'
.venv/bin/python -m scouter setup # installs the Lua plugin (persistently), reports doctor,
# prints the `claude mcp add` line -- exits 0 even with no
# darktable running yet (doctor is not required here)
# restart darktable (it loads the plugin at launch), open a photo in the darkroom, then:
scouter setup --check # every item ok, doctor included? exit 0; anything missing? exit 1, changes nothing
scouter setup is idempotent and does, in order:
| Item | What it does | --check reports |
|---|---|---|
plugin |
writes the packaged darktable_mcp.lua where the bridge reads it (~/.config/darktable/lua/, or $DARKTABLE_MCP_PLUGIN_PATH) and leaves it installed -- no uninstall on exit, unlike the host tests |
ok / missing / stale (an older plugin) |
luarc |
adds require "darktable_mcp" to ~/.config/darktable/luarc once, keeping every other line |
ok / missing |
wb_tables |
copies the measured white-balance tables shipped in scouter/data/wb/ (today: em10iii) into <config_dir>/wb/ when that camera has none; never overwrites one |
ok / missing, plus any other calibrated bodies |
config |
reported only: scouter config init writes it, because the backup gate is yours to arm. Single-frame editing works without it |
ok / missing (not required, either way) |
doctor |
the bridge half of scouter doctor: darktable running, plugin loaded, answering |
ok / bridge_timeout / ... -- required only under --check |
It then prints the exact claude mcp add command and the equivalent JSON
(see "Editing with Scouter from Claude Code" below). It never reads or writes
Claude Code's own config; registering is one command you run yourself.
The exit code is 0 when every required item is ok -- and on a plain
scouter setup (no --check), doctor is not required: a fresh install
with no darktable running yet still exits 0, installing the plugin and
printing a next hint that explains what doctor verifies and how to
confirm it (restart darktable, then scouter setup --check). --check is
the explicit "is this healthy right now" ask, and keeps doctor required,
so it still exits 1 until darktable answers.
darktable-mcp install-plugin still exists and writes the same two files.
darktable must be running, with the image open in the darkroom: slider
actions exist only there, and scouter says so (wrong_view, exit code 4)
instead of failing quietly.
Leave darktable's own store XMP sidecar files preference at a setting that
writes sidecars (the default on import and after edit): the XMP sidecar is
how Scouter reads every value back. Scouter never reads or changes that
preference — it cannot, from Lua (a dt.preferences.write for it only
creates a script-namespaced key and leaves the core setting alone, which an
earlier round proved the hard way). With sidecar writing off, a commit simply
never lands and scouter reports commit_timeout (exit 10) rather than
claiming a write it cannot see.
The plugin loads through ~/.config/darktable/luarc (require "darktable_mcp"),
same as the original darktable-mcp tools.
A hero edit
scouter darkroom open ~/Pictures/EditingTrial/P6281348.ORF
scouter darkroom set exposure exposure 1.2
scouter darkroom set sigmoid contrast 1.35
scouter --pretty scout stats ~/Pictures/EditingTrial/P6281348.ORF --px 1024
scouter darkroom undo-last
scouter --pretty history read ~/Pictures/EditingTrial/P6281348.ORF
--pretty and --job belong to scouter itself, so they go before the
group and command (scouter --pretty scout stats ...); per-verb flags such as
--px, --dry-run and --yes go after it. --pretty is also accepted
after the group/command (scouter cull propose --job-slug .. --pretty, as
the phase 2 examples below show) — both positions work the same way.
Every write is one darktable history item you can see and undo yourself.
undo-last sets the parameter back to its previous value, which adds a history
item rather than rewriting history — so your own Ctrl-Z still works.
Safety
- Writers take
--dry-run; gated verbs (darkroom reset,style extractover an existing name,export runover existing files or more than one image) print the plan and do nothing until--yes.style applyalways appends to history;--mode overwriteis not a gate but a refusal — it fails immediately withunsupported_mode, before anything reaches darktable, because no--yescan make darktable replace a history it has no API to replace. - Scouter never renders its own pixels, and never touches
library.db. Pixels come fromdarktable-cliin an isolated config dir; edits go throughdt.gui.action; history is read from the XMP sidecar.
Scouter MCP questions
What tools does Scouter MCP provide?
It exposes 10 tools, including view_photos, rate_photos, import_batch, list_styles, apply_preset.
How does Scouter ensure photo edits are applied correctly?
Scouter confirms every write by reading the XMP sidecar back. If darktable writes an older history over it, Scouter refuses the write and restores the sidecar.
Can I use Scouter to import photos from a camera?
Yes, the server includes a tool to detect a camera via libgphoto2 and copy photos to a local directory, supporting both PTP and USB Mass-Storage.
Does Scouter modify the darktable library database directly?
No, Scouter never writes to darktable's library.db and uses the official Lua API and darktable-cli instead.
How can I preview the edits made by the AI?
The server can render previews using darktable-cli in an isolated configuration so the agent can view the result.