LosslessCut MCP

Work in progress — not a production-ready release. The MCP implementation and roadmap are still being verified. Capability counts, source-mapping coverage, current tasks, and evidence are maintained in the status dashboard, capability register, and roadmap. No release has been published.

LosslessCut MCP prepares and exports precise cuts through LosslessCut's native editor and project format. It is not a generic FFmpeg tool server: LosslessCut performs edits and exports; FFprobe inspects and checks media.

The current prototype prepares and inspects LLC projects, creates projects from supported segment sources, analyzes media, and requests native exports. Native export evidence is limited to Fedora/Linux with a source-built LosslessCut 3.69.0 (448348bd) plus a private hidden-background-mode patch. Compatibility with official LosslessCut 3.70.2 has not yet passed native acceptance. The complete supported and missing feature scope is in the capability register; the domain ontology explains the evidence and runtime boundaries.

Project progress

• Status dashboard: verified coverage, source-operation mapping, current factory state, immediate tasks, and known blockers.

• Roadmap: task-level implementation plan, dependencies, and acceptance criteria.

• Source action inventory: upstream operations mapped to MCP capabilities.

• Architecture and feasibility evidence · native and protocol evidence: supported topology, observed behavior, and limitations.

• Factory operations · local dashboard · SWE Agent Kit integration: development workflow and retained engineering evidence.

The autonomous factory is not running unattended: the status report records the service as absent/stopped and no active worker. The dashboard is a read-only local view, not a scheduler. See the factory operations report for its activation gates and current limitations.

Related MCP server: DCC-MCP Kdenlive

Tools

• losslesscut_api_status checks the API root and verifies the upstream Host/Origin guard.

• losslesscut_extract_all_streams extracts supported timed streams, attachments and cover art to deterministic individual outputs, verifying outputs and refusing unsupported containers or stream types. This offline FFmpeg operation does not change editor state or source media.

• losslesscut_inspect_media runs FFprobe on an authorized media file and reports container/stream facts, metadata tags, and chapter ranges; it does not inspect editor state.

• losslesscut_inspect_project reads and validates an authorized LLC v1/v2 project, its segment ranges, and any referenced media path.

• losslesscut_create_project creates a new LLC v2 project from an authorized source and validated segment ranges. It refuses overwrite, preserves the media file, and does not export.

• losslesscut_import_csv_segments imports a LosslessCut CSV segment list (seconds or human time, names and tags) into a new LLC project. It rejects markers, malformed ranges and out-of-root paths; it does not export.

• losslesscut_export_segments_csv writes LLC segments and markers to a new CSV file with decimal-second timestamps, names, and tag columns. It refuses overwrite and does not modify project or media.

• losslesscut_export_youtube_chapters writes embedded media chapters or definite LLC segments to a new authorized .txt file, enforcing YouTube timestamp rules and leaving the source unchanged.

• losslesscut_edit_metadata writes allowlisted global or per-stream metadata edits to a new Matroska file, then verifies metadata and packet preservation. It does not change the source or pending LosslessCut editor state.

• losslesscut_extract_gps_track reads supported GPS subtitle telemetry into structured data without geocoding or network access.

• losslesscut_analyze_silence runs FFmpeg's silencedetect against an authorized media file and returns candidate silence/retained ranges. It is external analysis, writes no file, and does not alter LosslessCut state.

• losslesscut_extract_audio_stream copies one selected audio stream to a new .mka output and verifies stream properties and decodability.

• losslesscut_analyze_keyframes uses FFprobe to report encoded keyframe timestamps for an authorized video stream. It is external inspection and does not guarantee that LosslessCut can cut at every reported timestamp without re-encoding.

• losslesscut_create_project_from_silence creates a new reviewable LLC project from the retained intervals reported by external silence analysis. It refuses overwrite and never starts an export.

• losslesscut_create_project_from_chapters creates a new reviewable LLC project from all embedded chapters or caller-selected chapter indices, preserving chapter names and tags. It refuses overwrite and never starts an export.

• losslesscut_analyze_black_scenes uses FFmpeg's blackdetect filter to return candidate black and retained intervals for review. It writes no files and does not invoke native LosslessCut detection.

• losslesscut_create_project_with_fixed_segments creates contiguous selected LLC segments of a chosen duration, with a shorter final segment when needed. LosslessCut performs any later export; source media is unchanged.

• losslesscut_create_project_from_black_scenes creates a reviewable LLC project from retained intervals identified by external FFmpeg black detection. It refuses overwrite and does not export.

• losslesscut_revise_project creates a new LLC v2 revision from an existing project and a supplied ordered segment list. It preserves unknown top-level fields, leaves the original project and media unchanged, refuses overwrite, and does not export.

• losslesscut_split_project_segment creates a new LLC v2 revision with one definite segment split at supplied interior times. It preserves names/tags/selection and leaves the source project/media unchanged.

• losslesscut_invert_project creates a new LLC project for the gaps around the source project's definite cut ranges. Exporting it creates separate retained clips; it does not merge them.

• losslesscut_open_project opens an authorized .llc project. The result is explicitly unverified because LosslessCut currently returns HTTP 200 even when renderer actions fail.

• losslesscut_set_stream_disposition changes one allowlisted disposition in a new supported Matroska/WebM or MP4 output, verifying streams and tags while preserving the input.

• losslesscut_export_project opens a project and verifies newly created outputs with FFprobe. Separate files are the default; mode: "merged" requests one native merge and verifies its duration within 0.25 seconds. Configure the private profile for the requested mode before connecting. Ambiguous or confirmation-blocked runs return uncertain; do not blindly retry them.

Media inspection, LLC inspection and project creation work without a running LosslessCut process. The supported export mode is an MCP-owned private, hidden LosslessCut instance. Set LOSSLESSCUT_EXECUTABLE, LOSSLESSCUT_CONFIG_DIR, LOSSLESSCUT_USER_DATA_DIR, and LOSSLESSCUT_BACKGROUND_MODE=required together. The executable must implement upstream's --mcp-background option and report its mode through the API response header; otherwise startup is refused and the MCP never treats a visible session as owned. This option is being prototyped separately in the upstream source checkout and is not yet part of an official LosslessCut release. Attaching to a shared GUI/API session is unsupported for exports: concurrent MCP servers or GUI actions can race its uncorrelated events. The experimental loopback API remains unauthenticated between local processes, so even private profile ownership cannot prevent other local software from calling that API. Keep the API on loopback and use a dedicated profile. The Linux acceptance harness uses disposable profiles and leaves unrelated applications untouched.

Quick start

Requirements: Linux, Node.js 22.23.3, npm 10.9.9, FFmpeg and FFprobe. You can set LOSSLESSCUT_FFMPEG_PATH, LOSSLESSCUT_FFPROBE_PATH, and LOSSLESSCUT_ANALYSIS_TIMEOUT_MS to select binaries and bound analysis time. Native acceptance additionally requires the source-built LosslessCut executable with --http-api support; CI runs the deterministic protocol suite but does not attempt GUI acceptance.

npm ci
npm run check:toolchain
npm run build
npm run typecheck
npm run format:check
npm run lint
npm test
npm run test:protocol

Before starting the MCP server, prepare a dedicated LosslessCut config and user-data directory and an existing output directory. Seed config.json so the private profile has the safe export settings the MCP checks:

mkdir -p /home/alex/losslesscut-profile/config /home/alex/losslesscut-profile/user-data
mkdir -p /home/alex/Videos/exports
cat > /home/alex/losslesscut-profile/config/config.json <<'JSON'
{
  "enableCustomOutDir": true,
  "recentCustomOutDirs": ["/home/alex/Videos/exports"],
  "enableOverwriteOutput": false,
  "autoMerge": false,
  "autoDeleteMergedSegments": false,
  "invertCutSegments": false,
  "segmentsToChaptersOnly": false,
  "enableAskForFileOpenAction": false,
  "askBeforeClose": true,
  "storeProjectInWorkingDir": true,
  "exportConfirmEnabled": false,
  "cleanupChoices": { "cleanupAfterExport": false }
}
JSON

Use a dedicated, private config directory and user-data directory; these must not belong to an unrelated LosslessCut session. Startup fails if the API port is occupied, the API security guard is absent, or the renderer readiness marker does not arrive before LOSSLESSCUT_STARTUP_TIMEOUT_MS (default 30000). MCP stops the exact child process it started on shutdown. This is tested on the source-built Linux application only; no cross-platform support is claimed.

Replace the example paths below with real absolute paths. Configure your MCP client to run the built server. This is a Claude Desktop-style claude_desktop_config.json example; other stdio MCP clients use the same command and environment values:

{
  "mcpServers": {
    "losslesscut": {
      "command": "node",
      "args": ["/home/alex/src/losslesscut-mcp/dist/index.js"],
      "env": {
        "LOSSLESSCUT_API_PORT": "18080",
        "LOSSLESSCUT_ALLOWED_ROOTS": "/home/alex/Videos",
        "LOSSLESSCUT_EXECUTABLE": "/home/alex/Applications/losslesscut",
        "LOSSLESSCUT_CONFIG_DIR": "/home/alex/losslesscut-profile/config",
        "LOSSLESSCUT_USER_DATA_DIR": "/home/alex/losslesscut-profile/user-data",
        "LOSSLESSCUT_BACKGROUND_MODE": "required",
        "LOSSLESSCUT_EXPORT_TIMEOUT_MS": "120000"
      }
    }
  }
}

The MCP-owned process receives --http-api, --config-dir, and --mcp-background itself. The config must select separate-segment export, disable overwrite and open confirmation, leave cleanup-after-export disabled, and name the requested existing empty output directory as its custom output directory. Export is refused unless these settings can be read and checked. Keep the API bound to loopback and use an upstream build that confirms background mode and rejects hostile Host and browser Origin headers; the server refuses owned-session startup if either mode or guard is unverified. The loopback API is unauthenticated against other local processes. Shared GUI/API exports are unsupported.

For merge-only export, configure the private profile before the MCP server starts with autoMerge: true and autoDeleteMergedSegments: true; then call losslesscut_export_project with mode: "merged". The MCP will reject a mode/profile mismatch. A single profile cannot safely switch export modes during the same MCP connection.

After the client starts the server, request the tools from its tool list. The server process owns LosslessCut for the duration of that MCP connection; closing the client connection triggers shutdown of the exact child it launched.

To run the real acceptance test on Fedora/Linux:

LOSSLESSCUT_EXECUTABLE=/path/to/losslesscut npm run test:acceptance

The harness starts and terminates only the instances it owns. Set LOSSLESSCUT_KEEP_TEST_OUTPUT=1 to preserve generated inputs, outputs, and logs. See architecture, feasibility evidence, capability matrix, and roadmap. The proposed first release notes are in docs/RELEASE_NOTES.md; no release has been published.

For the project-scoped SWE Agent Kit integration, installed skill/agent manifest, evidence/runtime boundaries, and current factory limits, see docs/ENGINEERING_KIT.md and docs/FACTORY_OPERATIONS.md.

License

MIT. LosslessCut is a separate GPL-2.0-licensed application; this project communicates through its HTTP API and project files and does not copy or link its implementation.