Shotcut MCP
MCPB · SHOTCUT-MCP-1.5.1.MCPB · SCANNED AUG 3
Create, edit, validate, preview, and render Shotcut projects through AI clients.
Available components
42 42 Trust /100
Trust breakdown (6 categories)
How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. How we score →
Supply Chain Security13
- Malware scan not yet available for this package.Unverified
- CVE data not yet available for this package.Unverified
- No install/post-install scripts declared.Pass
- Dependency-health data not yet available.Unverified
Provenance & Transparency45
- Source repository is publicly reachable at the declared URL. View diagnostics → Pass
- Provenance check failed: no build-provenance attestation is published. See how to fix → View diagnostics → Fail
- Clear OSI-approved license (MIT).Pass
- Actively maintained (last published 1 days ago).Pass
- Disclosure check failed: no security disclosure policy was found in the source repository. See how to fix → Fail
Schema Quality & AI Usability69
- AI-judged instruction clarity (excellent).Pass
- Context-footprint check failed: tool/resource definitions use about 3712 tokens (~142/item across 26 items; 26 tools + 0 resources), over budget; trim descriptions and params. See how to fix → Fail
- Usage-examples check failed: none of the tools include examples. See how to fix → Fail
Stability & Change Management0
- Stability not yet verified: not enough scan history yet (needs a 30-day window).Unverified
Tool Coverage100
- 100% of tools have a non-trivial description (not blank, and not just the tool's name).Pass
- 100% of tool parameters carry a description.Pass
- Structured output schemas are declared (100% of tools); any adoption earns full credit.Pass
Capabilities100
- Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.Pass
Unverified: 1 category
A category scored 0 because we could not verify it: a data source with nothing on this package, evidence we could not reach, or a check we could not run. We only credit what we can confirm.
Install
Add this component to your MCP client. Where a client-specific snippet is available, pick your client below and copy it straight into your config; otherwise use the connection detail shown.
mcpb · shotcut-mcp-1.5.1.mcpb
Download bundle Changelog
Every change we have recorded for this component, newest first. Security-relevant changes are always shown. ▲ marks a change for the better, ▼ a change for the worse; unmarked changes are neutral.
- 2 Aug 26 42
First indexed and scored.
Diagnostics
Diagnostic detail from the automated scan of this channel: what the scanner observed at each step, so you can see exactly where a check passed or failed. It is informational only and never changes the trust score.
Captured 3 Aug 2026 · Analysed mcpb/https://github.com/matrodrigs/shotcut-mcp/releases/download/v1.5.1/shotcut-mcp-1.5.1.mcpb
Provenance none
Ecosystem: mcpb · Outcome: none
MCP tools
— 26 exposed
· ~3,178 tokens
The tools this component advertises to a client, with an estimated token cost for each. Expand a tool to see its parameters and schema. The per-tool counts are indicative and are not scored directly; the schema's total context footprint is one signal in Schema Quality & AI Usability.
Tool
Tokens
analyze_media_quality Analyze media quality ~348
Use before proposing cleanup or delivery edits. Runs installed FFmpeg analyzers for silence, black frames, freezes, interlacing, and loudness and returns bounded structured measurements without changing the media.
| Name | Type | Req | Description |
|---|---|---|---|
| analyzers | array | — | Quality checks to run; defaults to every analyzer supported by this tool. |
| audio_stream_index | integer | — | Optional global FFprobe stream index for the audio checks. |
| black_min_duration_seconds | number | — | Minimum continuous black-frame duration to report. |
| black_picture_threshold | number | — | Fraction of qualifying dark pixels required for a black frame. |
| black_pixel_threshold | number | — | Per-pixel luminance threshold used by FFmpeg blackdetect. |
| dual_mono | boolean | — | Measure mono input as dual-mono when computing EBU R128 loudness. |
| duration_seconds | number | — | Optional bounded media duration in seconds to analyze. |
| freeze_min_duration_seconds | number | — | Minimum continuous frozen-video duration to report. |
| freeze_noise_db | number | — | Frame-difference tolerance in dB used by FFmpeg freezedetect. |
| max_intervals | integer | — | Maximum structured intervals retained per analyzer. |
| path | string | yes | Existing authorized local project, media, folder, or backup path. |
| silence_min_duration_seconds | number | — | Minimum continuous silence duration to report. |
| silence_threshold_db | number | — | Audio level in dB at or below which a segment counts as silence. |
| start_seconds | number | — | Optional media offset in seconds where analysis begins. |
| timeout_seconds | integer | — | Bounded timeout for local MLT processing. |
| video_stream_index | integer | — | Optional global FFprobe stream index for the video checks. |
| Name | Type | Req | Description |
|---|---|---|---|
| analyzers | object | — | — |
| current_revision | string|null | — | — |
| details | object | — | Bounded structured context specific to the error code. |
| duration_seconds | number|null | — | — |
| error | string | — | Human-readable failure summary. |
| error_code | string | — | Stable machine-readable Shotcut MCP error code. |
| error_type | string | — | Stable Python exception family retained for compatibility. |
| expected_revision | string|null | — | — |
| media_duration_seconds | number|null | — | — |
| path | string | — | — |
| recommended_action | string | — | Machine-readable next action for the caller. |
| recommended_tool | string|null | — | MCP tool to call next when one action is preferred. |
| recoverable | boolean | — | Whether the caller can take a safe corrective action. |
| requested_analyzers | array | — | Analyzer names requested by the caller. |
| start_seconds | number | — | — |
| streams | object | — | Selected global FFprobe stream indexes. |
No examples provided.
cancel_render Cancel render ~49
Use only when the user asks to stop an active render. Requests supervised cancellation, including after an MCP restart.
| Name | Type | Req | Description |
|---|---|---|---|
| job_id | string | yes | Durable render identifier returned by start_render or list_render_jobs. |
| Name | Type | Req | Description |
|---|---|---|---|
| cancellation_requested | boolean | — | — |
| current_revision | string|null | — | — |
| details | object | — | Bounded structured context specific to the error code. |
| elapsed_seconds | number | — | — |
| error | string | — | Human-readable failure summary. |
| error_code | string | — | Stable machine-readable Shotcut MCP error code. |
| error_type | string | — | Stable Python exception family retained for compatibility. |
| eta_confidence | string|null | — | — |
| eta_seconds | number|null | — | — |
| expected_revision | string|null | — | — |
| in_frame | integer|null | — | — |
| job_id | string | — | — |
| log_tail | string|null | — | — |
| out_frame | integer|null | — | — |
| output_exists | boolean | — | — |
| output_path | string | — | — |
| output_size_bytes | integer|null | — | — |
| progress_percent | number|null | — | — |
| range_duration_frames | integer|null | — | — |
| recommended_action | string | — | Machine-readable next action for the caller. |
| recommended_tool | string|null | — | MCP tool to call next when one action is preferred. |
| recoverable | boolean | — | Whether the caller can take a safe corrective action. |
| status | string | — | — |
No examples provided.
create_project Create multitrack Shotcut project ~224
Use to create a new editable Shotcut 26.6 project. If dimensions or frame rate were not requested, probe representative source media before choosing the profile; do not treat defaults as user intent. Tracks and clips use the same shapes as add_track and add_clip.
| Name | Type | Req | Description |
|---|---|---|---|
| clips | array | — | Initial clips using add_clip fields; track defaults to V1. |
| fps_den | integer | — | Project frame-rate denominator. |
| fps_num | integer | — | Project frame-rate numerator. |
| height | integer | — | Project height in pixels. |
| notes | string | — | Initial project notes. |
| overwrite | boolean | — | Replace an existing destination only when the user explicitly authorized it. |
| project_path | string | yes | Existing authorized Shotcut .mlt or .xml project path, except when create_project creates it. |
| timeout_seconds | integer | — | Bounded timeout for local MLT processing. |
| tracks | array | — | Initial tracks using add_track fields; V1 already exists. |
| width | integer | — | Project or contact-sheet width in pixels, depending on the tool. |
| Name | Type | Req | Description |
|---|---|---|---|
| backup_path | string|null | — | — |
| created | boolean | — | — |
| current_revision | string|null | — | — |
| details | object | — | Bounded structured context specific to the error code. |
| error | string | — | Human-readable failure summary. |
| error_code | string | — | Stable machine-readable Shotcut MCP error code. |
| error_type | string | — | Stable Python exception family retained for compatibility. |
| expected_revision | string|null | — | — |
| operation_results | array | — | Results for initial track and clip operations. |
| path | string | — | — |
| previous_revision | string|null | — | — |
| project | object | — | Project snapshot; inspect_project publishes its complete schema. |
| recommended_action | string | — | Machine-readable next action for the caller. |
| recommended_tool | string|null | — | MCP tool to call next when one action is preferred. |
| recoverable | boolean | — | Whether the caller can take a safe corrective action. |
| revision | string | — | — |
| validation | object | — | Result of processing the project with local Melt. |
No examples provided.
describe_mlt_service Describe MLT service ~61
Use after list_mlt_services to learn one installed service's accepted properties and local MLT metadata.
| Name | Type | Req | Description |
|---|---|---|---|
| kind | string | yes | MLT service kind to list or describe. |
| name | string | yes | Exact service name returned by list_mlt_services. |
| Name | Type | Req | Description |
|---|---|---|---|
| available | boolean | — | — |
| current_revision | string|null | — | — |
| details | object | — | Bounded structured context specific to the error code. |
| error | string | — | Human-readable failure summary. |
| error_code | string | — | Stable machine-readable Shotcut MCP error code. |
| error_type | string | — | Stable Python exception family retained for compatibility. |
| expected_revision | string|null | — | — |
| kind | string | — | — |
| metadata | string|null | — | — |
| name | string | — | — |
| recommended_action | string | — | Machine-readable next action for the caller. |
| recommended_tool | string|null | — | MCP tool to call next when one action is preferred. |
| recoverable | boolean | — | Whether the caller can take a safe corrective action. |
No examples provided.
detect_hardware_encoders Detect usable hardware encoders ~49
Use when choosing or troubleshooting hardware export. Lists advertised FFmpeg encoders and smoke-tests OS-appropriate candidates.
| Name | Type | Req | Description |
|---|---|---|---|
| refresh | boolean | — | Ignore cached encoder results and run smoke tests again. |
| Name | Type | Req | Description |
|---|---|---|---|
| candidates | array | — | OS-appropriate hardware encoder smoke tests. |
| current_revision | string|null | — | — |
| details | object | — | Bounded structured context specific to the error code. |
| error | string | — | Human-readable failure summary. |
| error_code | string | — | Stable machine-readable Shotcut MCP error code. |
| error_type | string | — | Stable Python exception family retained for compatibility. |
| expected_revision | string|null | — | — |
| ffmpeg_path | string | — | — |
| note | string | — | — |
| platform | string | — | — |
| recommended_action | string | — | Machine-readable next action for the caller. |
| recommended_tool | string|null | — | MCP tool to call next when one action is preferred. |
| recoverable | boolean | — | Whether the caller can take a safe corrective action. |
| suggestions | object | — | — |
No examples provided.
diagnose_color_workflow Diagnose project color workflow ~101
Use for washed-out colors, HDR/SDR questions, or export compatibility. Reports normalized source color facts and Shotcut 26.6 issues.
| Name | Type | Req | Description |
|---|---|---|---|
| hdr10_metadata | boolean | — | Whether the intended export requires HDR10 metadata. |
| output_codec | string | — | Optional intended export codec used to assess color compatibility. |
| project_path | string | yes | Existing authorized Shotcut .mlt or .xml project path, except when create_project creates it. |
| Name | Type | Req | Description |
|---|---|---|---|
| compatible | boolean | — | — |
| current_revision | string|null | — | — |
| details | object | — | Bounded structured context specific to the error code. |
| error | string | — | Human-readable failure summary. |
| error_code | string | — | Stable machine-readable Shotcut MCP error code. |
| error_type | string | — | Stable Python exception family retained for compatibility. |
| expected_revision | string|null | — | — |
| issues | array | — | Color-workflow compatibility findings. |
| media | array | — | Bounded source-media summaries or probe errors. |
| media_truncated | boolean | — | — |
| project_color_workflow | object | — | Normalized Shotcut project color workflow. |
| project_path | string | — | — |
| recommended_action | string | — | Machine-readable next action for the caller. |
| recommended_tool | string|null | — | MCP tool to call next when one action is preferred. |
| recoverable | boolean | — | Whether the caller can take a safe corrective action. |
| source_dynamic_ranges | array | — | Distinct detected source dynamic ranges. |
No examples provided.
diagnose_missing_media Find missing-media candidates ~251
Use when media is missing or offline. Searches authorized roots and ranks candidates; never relinks automatically, so let the user choose first.
| Name | Type | Req | Description |
|---|---|---|---|
| max_candidates_per_resource | integer | — | Maximum ranked candidates returned for each missing resource. |
| max_depth | integer | — | Maximum directory depth below each search root. |
| max_files | integer | — | Maximum files examined across all search roots. |
| max_hash_bytes | integer | — | Largest candidate file eligible for Shotcut hash verification. |
| max_probe_candidates | integer | — | Maximum candidates inspected with FFprobe. |
| overwrite_visual | boolean | — | Replace an existing candidate sheet only with explicit authorization. |
| project_path | string | yes | Existing authorized Shotcut .mlt or .xml project path, except when create_project creates it. |
| search_roots | array | yes | One to eight authorized roots searched for missing-media candidates. |
| timeout_seconds | integer | — | Bounded timeout for local MLT processing. |
| visual_cell_width | integer | — | Width of each optional missing-media candidate cell in pixels. |
| visual_columns | integer | — | Columns in the optional missing-media candidate sheet. |
| visual_output_path | string | — | Optional PNG/JPEG destination for a missing-media candidate sheet. |
| Name | Type | Req | Description |
|---|---|---|---|
| commit_workflow | string | — | — |
| current_revision | string|null | — | — |
| details | object | — | Bounded structured context specific to the error code. |
| error | string | — | Human-readable failure summary. |
| error_code | string | — | Stable machine-readable Shotcut MCP error code. |
| error_type | string | — | Stable Python exception family retained for compatibility. |
| expected_revision | string|null | — | — |
| missing_count | integer | — | — |
| project_path | string | — | — |
| recommended_action | string | — | Machine-readable next action for the caller. |
| recommended_tool | string|null | — | MCP tool to call next when one action is preferred. |
| recoverable | boolean | — | Whether the caller can take a safe corrective action. |
| resources | array | — | Missing resources and their ranked replacement candidates. |
| search | object | — | Bounded search telemetry. |
| visual | object|null | — | — |
No examples provided.
edit_project Edit project transactionally ~184
Use only after inspect_project. Applies up to 500 related operations in one validated atomic write; prefer item_ref and animate_clip for robust creative batches. Pass expected_revision and re-inspect on conflicts instead of force. Summarize committed operation results, and after visual edits show a managed contact sheet or exact preview.
| Name | Type | Req | Description |
|---|---|---|---|
| expected_revision | string | — | SHA-256 revision returned by inspect_project. Required unless force=true was explicitly authorized. |
| force | boolean | — | Bypass revision protection only with explicit user authorization; never retry conflicts with force automatically. |
| operations | array | yes | One or more related edit operations. Query shotcut_capabilities for unfamiliar operation schemas. |
| project_path | string | yes | Existing authorized Shotcut .mlt or .xml project path, except when create_project creates it. |
| timeout_seconds | integer | — | Bounded timeout for local MLT processing. |
| Name | Type | Req | Description |
|---|---|---|---|
| backup_path | string|null | — | — |
| current_revision | string|null | — | — |
| details | object | — | Bounded structured context specific to the error code. |
| edited | boolean | — | — |
| error | string | — | Human-readable failure summary. |
| error_code | string | — | Stable machine-readable Shotcut MCP error code. |
| error_type | string | — | Stable Python exception family retained for compatibility. |
| expected_revision | string|null | — | — |
| item_bindings | object | — | Batch aliases mapped to item_ref values for the committed revision. |
| operation_results | array | — | Results in the same order as the requested operations. |
| path | string | — | — |
| previous_revision | string|null | — | — |
| project | object | — | Project snapshot; inspect_project publishes its complete schema. |
| recommended_action | string | — | Machine-readable next action for the caller. |
| recommended_tool | string|null | — | MCP tool to call next when one action is preferred. |
| recoverable | boolean | — | Whether the caller can take a safe corrective action. |
| revision | string | — | — |
| validation | object | — | Result of processing the project with local Melt. |
No examples provided.
export_marker_chapters Export marker chapters ~184
Use to create Shotcut-compatible chapter text from point markers. Optionally includes range markers or selected marker colors and atomically protects an existing output.
| Name | Type | Req | Description |
|---|---|---|---|
| colors | array | — | Optional marker-color allowlist using Shotcut #RRGGBB values. |
| expected_revision | string | — | Optional SHA-256 revision returned by inspect_project. When supplied, export fails if the project has changed. |
| include_range_markers | boolean | — | Include Shotcut range markers as chapters; point markers are included by default. |
| output_path | string | yes | Authorized destination path. Omit only for single-frame or contact-sheet previews to use bounded managed output. |
| overwrite | boolean | — | Replace an existing destination only when the user explicitly authorized it. |
| project_path | string | yes | Existing authorized Shotcut .mlt or .xml project path, except when create_project creates it. |
| Name | Type | Req | Description |
|---|---|---|---|
| chapter_count | integer | — | — |
| chapters | array | — | Exported chapters in playback order. |
| colors | array|null | — | Applied marker-color allowlist. |
| created | boolean | — | — |
| current_revision | string|null | — | — |
| details | object | — | Bounded structured context specific to the error code. |
| error | string | — | Human-readable failure summary. |
| error_code | string | — | Stable machine-readable Shotcut MCP error code. |
| error_type | string | — | Stable Python exception family retained for compatibility. |
| expected_revision | string|null | — | — |
| include_range_markers | boolean | — | — |
| marker_count | integer | — | — |
| path | string | — | — |
| project_path | string | — | — |
| project_revision | string | — | — |
| recommended_action | string | — | Machine-readable next action for the caller. |
| recommended_tool | string|null | — | MCP tool to call next when one action is preferred. |
| recoverable | boolean | — | Whether the caller can take a safe corrective action. |
| size_bytes | integer | — | — |
No examples provided.
inspect_project Inspect complete project ~67
Use first to understand a timeline or before planning, editing, or restoring. Returns structural state, SHA-256 revision, and revision-scoped item_ref selectors; use render_contact_sheet for visual review.
| Name | Type | Req | Description |
|---|---|---|---|
| path | string | yes | Existing authorized local project, media, folder, or backup path. |
| Name | Type | Req | Description |
|---|---|---|---|
| color_workflow | object | — | Normalized Shotcut project color workflow. |
| counts | object | — | Counts of important MLT element kinds. |
| current_revision | string|null | — | — |
| details | object | — | Bounded structured context specific to the error code. |
| duration_frames | integer | — | Project duration in frames. |
| error | string | — | Human-readable failure summary. |
| error_code | string | — | Stable machine-readable Shotcut MCP error code. |
| error_type | string | — | Stable Python exception family retained for compatibility. |
| expected_revision | string|null | — | — |
| filters | array | — | Project-level filters in host order. |
| links | array | — | MLT links in the project. |
| markers | array | — | Shotcut point and range markers. |
| missing_resources | array | — | Resolved local resource paths that do not exist. |
| network_resources | array | — | Network resource values embedded in the project. |
| notes | string|null | — | Project notes, when present. |
| path | string | — | Authorized project path that was inspected. |
| profile | object | — | MLT profile attributes plus computed fps. |
| recommended_action | string | — | Machine-readable next action for the caller. |
| recommended_tool | string|null | — | MCP tool to call next when one action is preferred. |
| recoverable | boolean | — | Whether the caller can take a safe corrective action. |
| resources | array | — | Media and data resources referenced by the project. |
| revision | string | — | SHA-256 revision to pass as expected_revision. |
| shotcut_editable | boolean | — | Whether the main tractor is marked as Shotcut-editable. |
| subtitles | array | — | Shotcut subtitle feeds. |
| tracks | array | — | Project tracks in main-tractor order. |
No examples provided.
list_mlt_services List MLT services ~49
Use when an edit needs an unfamiliar native MLT effect or transition. Lists services of one kind installed with Shotcut.
| Name | Type | Req | Description |
|---|---|---|---|
| kind | string | yes | MLT service kind to list or describe. |
| Name | Type | Req | Description |
|---|---|---|---|
| count | integer | — | — |
| current_revision | string|null | — | — |
| details | object | — | Bounded structured context specific to the error code. |
| error | string | — | Human-readable failure summary. |
| error_code | string | — | Stable machine-readable Shotcut MCP error code. |
| error_type | string | — | Stable Python exception family retained for compatibility. |
| expected_revision | string|null | — | — |
| kind | string | — | — |
| recommended_action | string | — | Machine-readable next action for the caller. |
| recommended_tool | string|null | — | MCP tool to call next when one action is preferred. |
| recoverable | boolean | — | Whether the caller can take a safe corrective action. |
| services | array | — | Installed MLT service names in sorted order. |
No examples provided.
list_project_backups List project backups ~61
Use before undo or recovery. Lists only backups owned by this project, including paths, revisions, sizes, and timestamps.
| Name | Type | Req | Description |
|---|---|---|---|
| project_path | string | yes | Existing authorized Shotcut .mlt or .xml project path, except when create_project creates it. |
| Name | Type | Req | Description |
|---|---|---|---|
| backup_count | integer | — | — |
| backups | array | — | Project-owned backups in newest-first order. |
| current_revision | string|null | — | — |
| details | object | — | Bounded structured context specific to the error code. |
| error | string | — | Human-readable failure summary. |
| error_code | string | — | Stable machine-readable Shotcut MCP error code. |
| error_type | string | — | Stable Python exception family retained for compatibility. |
| expected_revision | string|null | — | — |
| project_path | string | — | — |
| recommended_action | string | — | Machine-readable next action for the caller. |
| recommended_tool | string|null | — | MCP tool to call next when one action is preferred. |
| recoverable | boolean | — | Whether the caller can take a safe corrective action. |
No examples provided.
list_render_jobs List render history ~72
Use for 'the latest render', render history, or when job_id is unknown. Returns bounded newest-first durable summaries.
| Name | Type | Req | Description |
|---|---|---|---|
| cursor | string | — | Opaque cursor returned by the preceding render-history page. |
| limit | integer | — | Maximum render summaries returned. |
| status | string | — | Optional render state filter. |
| Name | Type | Req | Description |
|---|---|---|---|
| count | integer | — | — |
| current_revision | string|null | — | — |
| details | object | — | Bounded structured context specific to the error code. |
| error | string | — | Human-readable failure summary. |
| error_code | string | — | Stable machine-readable Shotcut MCP error code. |
| error_type | string | — | Stable Python exception family retained for compatibility. |
| expected_revision | string|null | — | — |
| jobs | array | — | Newest-first durable render summaries. |
| next_cursor | string|null | — | — |
| recommended_action | string | — | Machine-readable next action for the caller. |
| recommended_tool | string|null | — | MCP tool to call next when one action is preferred. |
| recoverable | boolean | — | Whether the caller can take a safe corrective action. |
| status_filter | string|null | — | — |
No examples provided.
open_in_shotcut Open in Shotcut ~74
Use only when the user asks to open the GUI. Opens a project, media file, or folder in Shotcut; MCP edits do not require this.
| Name | Type | Req | Description |
|---|---|---|---|
| fullscreen | boolean | — | Ask Shotcut to open fullscreen. |
| path | string | yes | Existing authorized local project, media, folder, or backup path. |
| Name | Type | Req | Description |
|---|---|---|---|
| current_revision | string|null | — | — |
| details | object | — | Bounded structured context specific to the error code. |
| error | string | — | Human-readable failure summary. |
| error_code | string | — | Stable machine-readable Shotcut MCP error code. |
| error_type | string | — | Stable Python exception family retained for compatibility. |
| expected_revision | string|null | — | — |
| opened | boolean | — | — |
| path | string | — | — |
| pid | integer | — | — |
| recommended_action | string | — | Machine-readable next action for the caller. |
| recommended_tool | string|null | — | MCP tool to call next when one action is preferred. |
| recoverable | boolean | — | Whether the caller can take a safe corrective action. |
No examples provided.
plan_project_edit Plan project edit ~169
Use for a dry run, uncertain edit, or user review before committing. Applies operations in memory using stable item_ref selectors when supplied, validates with MLT, and returns a snapshot and diff without changing the project.
| Name | Type | Req | Description |
|---|---|---|---|
| expected_revision | string | yes | Required SHA-256 revision returned by inspect_project; force is not supported by plan_project_edit. |
| max_diff_lines | integer | — | Maximum unified-diff lines returned by a dry run; zero suppresses diff text. |
| operations | array | yes | One or more related edit operations. Query shotcut_capabilities for unfamiliar operation schemas. |
| project_path | string | yes | Existing authorized Shotcut .mlt or .xml project path, except when create_project creates it. |
| timeout_seconds | integer | — | Bounded timeout for local MLT processing. |
| Name | Type | Req | Description |
|---|---|---|---|
| base_revision | string | — | — |
| changed | boolean | — | — |
| current_revision | string|null | — | — |
| details | object | — | Bounded structured context specific to the error code. |
| diff_lines | integer | — | — |
| diff_truncated | boolean | — | — |
| error | string | — | Human-readable failure summary. |
| error_code | string | — | Stable machine-readable Shotcut MCP error code. |
| error_type | string | — | Stable Python exception family retained for compatibility. |
| expected_revision | string|null | — | — |
| item_bindings | object | — | Batch aliases mapped to item_ref values for the resulting revision. |
| operation_results | array | — | Results in the same order as the requested operations. |
| planned | boolean | — | — |
| project | object | — | Project snapshot; inspect_project publishes its complete schema. |
| project_path | string | — | — |
| prospective_revision | string | — | — |
| recommended_action | string | — | Machine-readable next action for the caller. |
| recommended_tool | string|null | — | MCP tool to call next when one action is preferred. |
| recoverable | boolean | — | Whether the caller can take a safe corrective action. |
| unified_diff | string | — | — |
| validation | object | — | Result of processing the project with local Melt. |
No examples provided.
probe_media Probe media ~55
Use to understand a source file before editing. Reads duration, codecs, resolution, frame rate, color, and audio with per-file caching.
| Name | Type | Req | Description |
|---|---|---|---|
| path | string | yes | Existing authorized local project, media, folder, or backup path. |
| Name | Type | Req | Description |
|---|---|---|---|
| bit_rate | number|null | — | — |
| current_revision | string|null | — | — |
| details | object | — | Bounded structured context specific to the error code. |
| duration_seconds | number|null | — | — |
| error | string | — | Human-readable failure summary. |
| error_code | string | — | Stable machine-readable Shotcut MCP error code. |
| error_type | string | — | Stable Python exception family retained for compatibility. |
| expected_revision | string|null | — | — |
| format | string|null | — | — |
| path | string | — | — |
| recommended_action | string | — | Machine-readable next action for the caller. |
| recommended_tool | string|null | — | MCP tool to call next when one action is preferred. |
| recoverable | boolean | — | Whether the caller can take a safe corrective action. |
| size_bytes | integer | — | — |
| streams | array | — | Normalized audio, video, subtitle, and data streams. |
No examples provided.
render_contact_sheet Render a contact sheet ~186
Use for 'show me the edit', visual review, or a timeline overview. Renders exact frames or 12 evenly sampled frames into one image; omit output_path for managed output.
| Name | Type | Req | Description |
|---|---|---|---|
| cell_width | integer | — | Width of each contact-sheet cell in pixels. |
| columns | integer | — | Number of contact-sheet columns. |
| frames | array | — | Exact frames for the contact sheet. When present, sample_count is ignored. |
| output_path | string | — | Authorized destination path. Omit only for single-frame or contact-sheet previews to use bounded managed output. |
| overwrite | boolean | — | Replace an existing destination only when the user explicitly authorized it. |
| project_path | string | yes | Existing authorized Shotcut .mlt or .xml project path, except when create_project creates it. |
| sample_count | integer | — | Evenly sampled frame count used only when frames is omitted. |
| Name | Type | Req | Description |
|---|---|---|---|
| cells | array | — | Contact-sheet cells in display order. |
| columns | integer | — | — |
| created | boolean | — | — |
| current_revision | string|null | — | — |
| details | object | — | Bounded structured context specific to the error code. |
| error | string | — | Human-readable failure summary. |
| error_code | string | — | Stable machine-readable Shotcut MCP error code. |
| error_type | string | — | Stable Python exception family retained for compatibility. |
| expected_revision | string|null | — | — |
| managed_output | boolean | — | — |
| path | string | — | — |
| recommended_action | string | — | Machine-readable next action for the caller. |
| recommended_tool | string|null | — | MCP tool to call next when one action is preferred. |
| recoverable | boolean | — | Whether the caller can take a safe corrective action. |
| rows | integer | — | — |
| size_bytes | integer | — | — |
No examples provided.
render_preview Render preview frame ~121
Use to show or inspect one specific moment. Renders one PNG and returns its path; omit output_path for a bounded server-managed preview.
| Name | Type | Req | Description |
|---|---|---|---|
| frame | integer | — | Zero-based project frame to render. |
| output_path | string | — | Authorized destination path. Omit only for single-frame or contact-sheet previews to use bounded managed output. |
| overwrite | boolean | — | Replace an existing destination only when the user explicitly authorized it. |
| project_path | string | yes | Existing authorized Shotcut .mlt or .xml project path, except when create_project creates it. |
| Name | Type | Req | Description |
|---|---|---|---|
| created | boolean | — | — |
| current_revision | string|null | — | — |
| details | object | — | Bounded structured context specific to the error code. |
| error | string | — | Human-readable failure summary. |
| error_code | string | — | Stable machine-readable Shotcut MCP error code. |
| error_type | string | — | Stable Python exception family retained for compatibility. |
| expected_revision | string|null | — | — |
| frame | integer | — | — |
| managed_output | boolean | — | — |
| path | string | — | — |
| recommended_action | string | — | Machine-readable next action for the caller. |
| recommended_tool | string|null | — | MCP tool to call next when one action is preferred. |
| recoverable | boolean | — | Whether the caller can take a safe corrective action. |
| size_bytes | integer | — | — |
No examples provided.
render_preview_batch Render preview frames in batch ~102
Use when exact frames are needed as separate image files. Renders up to 64 requested frames; use render_contact_sheet for one overview image.
| Name | Type | Req | Description |
|---|---|---|---|
| overwrite | boolean | — | Replace an existing destination only when the user explicitly authorized it. |
| project_path | string | yes | Existing authorized Shotcut .mlt or .xml project path, except when create_project creates it. |
| requests | array | yes | Exact frame/output-path pairs; every output path must be unique. |
| Name | Type | Req | Description |
|---|---|---|---|
| created | integer | — | — |
| current_revision | string|null | — | — |
| details | object | — | Bounded structured context specific to the error code. |
| error | string | — | Human-readable failure summary. |
| error_code | string | — | Stable machine-readable Shotcut MCP error code. |
| error_type | string | — | Stable Python exception family retained for compatibility. |
| expected_revision | string|null | — | — |
| partial_completion_possible | boolean | — | — |
| recommended_action | string | — | Machine-readable next action for the caller. |
| recommended_tool | string|null | — | MCP tool to call next when one action is preferred. |
| recoverable | boolean | — | Whether the caller can take a safe corrective action. |
| requested | integer | — | — |
| results | array | — | Per-frame successes and bounded failures. |
No examples provided.
render_status Get render status ~84
Use when job_id is known; poll until a terminal state and surface meaningful status, progress, or ETA changes without narrating unchanged polls or raw logs. On completion, present both returned artifacts: rendered media and the exact editable project. Use list_render_jobs when the id is unknown.
| Name | Type | Req | Description |
|---|---|---|---|
| job_id | string | yes | Durable render identifier returned by start_render or list_render_jobs. |
| Name | Type | Req | Description |
|---|---|---|---|
| artifacts | array | — | Completed rendered media and exact editable project, otherwise empty. |
| current_revision | string|null | — | — |
| delivery_complete | boolean | — | — |
| details | object | — | Bounded structured context specific to the error code. |
| editable_project_exists | boolean | — | — |
| editable_project_path | string|null | — | — |
| elapsed_seconds | number | — | — |
| error | string | — | Human-readable failure summary. |
| error_code | string | — | Stable machine-readable Shotcut MCP error code. |
| error_type | string | — | Stable Python exception family retained for compatibility. |
| eta_confidence | string|null | — | — |
| eta_seconds | number|null | — | — |
| expected_revision | string|null | — | — |
| frames_completed | integer|null | — | — |
| in_frame | integer|null | — | — |
| job_id | string | — | — |
| log_tail | string|null | — | — |
| out_frame | integer|null | — | — |
| output_exists | boolean | — | — |
| output_path | string | — | — |
| output_size_bytes | integer|null | — | — |
| progress_percent | number|null | — | — |
| project_path | string | — | — |
| range_duration_frames | integer|null | — | — |
| recommended_action | string | — | Machine-readable next action for the caller. |
| recommended_tool | string|null | — | MCP tool to call next when one action is preferred. |
| recoverable | boolean | — | Whether the caller can take a safe corrective action. |
| rendered_project_revision | string|null | — | — |
| status | string | — | — |
No examples provided.
restore_project_backup Restore project backup ~142
Use after list_project_backups and confirmation of the selected backup. Validates and atomically restores it while backing up the current project; pass the current expected_revision unless force=true was explicitly authorized.
| Name | Type | Req | Description |
|---|---|---|---|
| backup_path | string | yes | Exact backup path returned by list_project_backups for this project. |
| expected_revision | string | — | SHA-256 revision returned by inspect_project. Required unless force=true was explicitly authorized. |
| force | boolean | — | Bypass revision protection only with explicit user authorization; never retry conflicts with force automatically. |
| project_path | string | yes | Existing authorized Shotcut .mlt or .xml project path, except when create_project creates it. |
| Name | Type | Req | Description |
|---|---|---|---|
| backup_path | string|null | — | — |
| current_revision | string|null | — | — |
| details | object | — | Bounded structured context specific to the error code. |
| error | string | — | Human-readable failure summary. |
| error_code | string | — | Stable machine-readable Shotcut MCP error code. |
| error_type | string | — | Stable Python exception family retained for compatibility. |
| expected_revision | string|null | — | — |
| path | string | — | — |
| previous_revision | string|null | — | — |
| recommended_action | string | — | Machine-readable next action for the caller. |
| recommended_tool | string|null | — | MCP tool to call next when one action is preferred. |
| recoverable | boolean | — | Whether the caller can take a safe corrective action. |
| restored | boolean | — | — |
| revision | string | — | — |
| validation | object | — | Result of processing the project with local Melt. |
No examples provided.
shotcut_capabilities Get editing capabilities ~63
Use before an unfamiliar edit. Omit operation for the catalog, presets, compatibility, and workflow; pass operation for only its complete schema, example, and transaction guarantees enforced by plan and edit.
| Name | Type | Req | Description |
|---|---|---|---|
| operation | string | — | Optional edit operation to describe in full. |
| Name | Type | Req | Description |
|---|---|---|---|
| compatibility | object | — | Validated editing stack and project format. |
| current_revision | string|null | — | — |
| details | object | — | Bounded structured context specific to the error code. |
| error | string | — | Human-readable failure summary. |
| error_code | string | — | Stable machine-readable Shotcut MCP error code. |
| error_type | string | — | Stable Python exception family retained for compatibility. |
| expected_revision | string|null | — | — |
| feature_guidance | object | — | — |
| operation_query | string | — | — |
| operations | object | — | Edit operations keyed by op name. |
| recommended_action | string | — | Machine-readable next action for the caller. |
| recommended_tool | string|null | — | MCP tool to call next when one action is preferred. |
| recoverable | boolean | — | Whether the caller can take a safe corrective action. |
| render_presets | object | — | — |
| transaction_guarantees | array | — | Safety and transaction guarantees that apply to edit operations. |
| workflow | array | — | Recommended end-to-end workflow. |
No examples provided.
shotcut_doctor Check Shotcut compatibility ~48
Use after installation, upgrade, or a setup failure. Verifies validated Shotcut/MLT versions, repository startup, RNNoise, FFmpeg quality-analyzer availability, and path policy.
Input schema present but exposes no named parameters.
| Name | Type | Req | Description |
|---|---|---|---|
| checks | object | — | — |
| compatible | boolean | — | — |
| current_revision | string|null | — | — |
| details | object | — | Bounded structured context specific to the error code. |
| error | string | — | Human-readable failure summary. |
| error_code | string | — | Stable machine-readable Shotcut MCP error code. |
| error_type | string | — | Stable Python exception family retained for compatibility. |
| expected_revision | string|null | — | — |
| path_policy | object | — | Effective server path and resource policy. |
| quality_analyzers | object | — | — |
| recommended_action | string | — | Machine-readable next action for the caller. |
| recommended_tool | string|null | — | MCP tool to call next when one action is preferred. |
| recoverable | boolean | — | Whether the caller can take a safe corrective action. |
| validated_stack | object | — | Validated Shotcut and MLT compatibility target. |
No examples provided.
shotcut_status Check Shotcut status ~43
Use for a quick readiness check. Locates Shotcut, Melt, FFprobe, and FFmpeg and reports their versions; use shotcut_doctor for compatibility diagnosis.
Input schema present but exposes no named parameters.
| Name | Type | Req | Description |
|---|---|---|---|
| current_revision | string|null | — | — |
| details | object | — | Bounded structured context specific to the error code. |
| environment_overrides | object | — | — |
| error | string | — | Human-readable failure summary. |
| error_code | string | — | Stable machine-readable Shotcut MCP error code. |
| error_type | string | — | Stable Python exception family retained for compatibility. |
| expected_revision | string|null | — | — |
| ffmpeg | object | — | Executable discovery and version result. |
| ffprobe | object | — | Executable discovery and version result. |
| melt | object | — | Melt discovery, version, and repository readiness. |
| path_policy | object | — | Effective server path and resource policy. |
| ready | boolean | — | — |
| recommended_action | string | — | Machine-readable next action for the caller. |
| recommended_tool | string|null | — | MCP tool to call next when one action is preferred. |
| recoverable | boolean | — | Whether the caller can take a safe corrective action. |
| shotcut | object | — | Executable discovery and version result. |
No examples provided.
start_render Start render ~289
Use only after the user explicitly requests export or approves a preflight summary of project, output, preset, range or duration, and overwrite behavior; never infer export from edit completion, and do not ask twice after an explicit request. Starts one revision-bound durable render and exact editable project snapshot; pass expected_revision when known and monitor job_id with render_status.
| Name | Type | Req | Description |
|---|---|---|---|
| consumer_properties | object | — | Up to 50 scalar MLT avformat properties. Safe names are allowlisted unless the administrator enables unsafe properties; prefer a named preset. |
| expected_revision | string | — | Optional SHA-256 revision returned by inspect_project. When supplied, rendering fails before creating job or output state if the saved project changed. |
| in_frame | integer | — | Inclusive first project frame; requires out_frame. |
| marker_id | string | — | Range marker id from inspect_project; mutually exclusive with explicit frames. |
| out_frame | integer | — | Inclusive last project frame; requires in_frame. |
| output_path | string | yes | Authorized destination path. Omit only for single-frame or contact-sheet previews to use bounded managed output. |
| overwrite | boolean | — | Replace an existing destination only when the user explicitly authorized it. |
| preset | string | — | Named safe export preset returned by shotcut_capabilities. |
| project_path | string | yes | Existing authorized Shotcut .mlt or .xml project path, except when create_project creates it. |
| Name | Type | Req | Description |
|---|---|---|---|
| current_revision | string|null | — | — |
| details | object | — | Bounded structured context specific to the error code. |
| editable_project_path | string | — | — |
| error | string | — | Human-readable failure summary. |
| error_code | string | — | Stable machine-readable Shotcut MCP error code. |
| error_type | string | — | Stable Python exception family retained for compatibility. |
| expected_revision | string|null | — | — |
| in_frame | integer|null | — | — |
| job_id | string | — | — |
| marker_id | string|null | — | — |
| marker_text | string|null | — | — |
| out_frame | integer|null | — | — |
| output_path | string | — | — |
| preset | string | — | — |
| project_path | string | — | — |
| project_revision | string|null | — | — |
| range_duration_frames | integer|null | — | — |
| recommended_action | string | — | Machine-readable next action for the caller. |
| recommended_tool | string|null | — | MCP tool to call next when one action is preferred. |
| recoverable | boolean | — | Whether the caller can take a safe corrective action. |
| render_project_path | string | — | — |
| rendered_project_revision | string | — | — |
| source_duration_frames | integer|null | — | — |
| source_project_path | string | — | — |
| status | string | — | — |
| total_frames | integer|null | — | — |
No examples provided.
validate_project Validate project with MLT ~102
Use when saved-project readiness is unknown or media/service dependencies changed before preview or render; edit_project already validates its candidate, so do not repeat this after every successful edit. Checks XML, local resources, required installed MLT services, and first-frame Melt processing; this is not visual-quality analysis.
| Name | Type | Req | Description |
|---|---|---|---|
| path | string | yes | Existing authorized local project, media, folder, or backup path. |
| timeout_seconds | integer | — | Bounded timeout for local MLT processing. |
| Name | Type | Req | Description |
|---|---|---|---|
| checks | object | — | Independent project dependency checks. |
| current_revision | string|null | — | — |
| details | object | — | Bounded structured context specific to the error code. |
| diagnostic | string|null | — | Bounded Melt diagnostic output, when present. |
| error | string | — | Human-readable failure summary. |
| error_code | string | — | Stable machine-readable Shotcut MCP error code. |
| error_type | string | — | Stable Python exception family retained for compatibility. |
| expected_revision | string|null | — | — |
| project | object | — | Project snapshot; inspect_project publishes its complete schema. |
| ready | boolean | — | Whether validation passed, local resources exist, and required MLT services were verified. |
| recommended_action | string | — | Machine-readable next action for the caller. |
| recommended_tool | string|null | — | MCP tool to call next when one action is preferred. |
| recoverable | boolean | — | Whether the caller can take a safe corrective action. |
| return_code | integer | — | Local Melt process exit code. |
| valid | boolean | — | Whether local Melt processed the first project frame successfully. |
No examples provided.