Shotstack MCP Server & CLI

What is the Shotstack MCP server & CLI?

The Shotstack MCP server & CLI is a free, open source program that lets AI agents inspect existing jobs/assets and run approved account operations for you, in 2 ways. The MCP server is what an AI app like Claude, Codex or Cursor connects to, through MCP (Model Context Protocol), the open standard AI apps use to call outside tools.

You ask in plain language. Your AI picks the right tool, and the server makes the call directly to the Shotstack API.

The CLI is the same program as commands. shotstack-cli list-models runs the same code your AI runs when you ask to inspect current available generation models, whether an agent like Claude Code runs it or you do.

What can you ask it?

Once it's set up, you ask the way you'd ask an assistant. These are real prompts it handles:

Try asking
Inspect this existing render without submitting another.
List models in my selected sandbox profile.
Submit only the edit I approve.
Render the chosen template with these exact merge values.
Ingest the public source URL I selected.
Keep the upload credential in my private file.

Shotstack already offers official CLI, local MCP and hosted MCP. This owned package adds enforced local mutation approval, private named account/environment profiles and exclusive private-file delivery of signed upload credentials.

How to install the Shotstack MCP server

Use the existing install box for local stdio MCP, CLI and the versioned desktop archive. Full client and OS setup follows below; Codex is the current priority.

Set up Shotstack access

Private API keys and environments

1. Sign in to your intended account at app.shotstack.io, open the account menu and choose API Keys.
2. Select the sandbox or production key for the task. Set SHOTSTACK_ENV=stage or v1 to match. Production is the default; a sandbox key does not turn production URLs into sandbox URLs.
3. Save the key in an owner-only token file outside repositories. Set SHOTSTACK_TOKEN_FILE to its absolute path. SHOTSTACK_API_KEY in private local settings is the alternative.
4. Run shotstack-cli doctor, then doctor --network. The network check requests available generation models and does not print their content.
5. Read the selected schema, review the exact edit/account action and confirm only that operation. Do not submit a production render merely to test installation.

Requests use x-api-key on the fixed api.shotstack.io origin, with /edit, /serve or /ingest and the selected /stage or /v1 prefix. This package does not accept arbitrary API hosts, forward keys through redirects or perform OAuth. login prints setup instructions; it neither saves keys nor creates accounts.

On macOS/Linux, use a private directory (0700) and regular token-only file (0600). Windows users must restrict the file's ACL to their user; POSIX mode checking does not establish Windows ACL protection. Token files cannot be symlinks or exceed 64 KB. They override environment keys and are cached until restart. GUI settings may differ from your shell environment.

Access, plans, credits and limits

The wrapper is free AGPL software. Shotstack access, rendering, generated assets, storage and serving follow the provider's account terms. No account role or OAuth scope bypass is supplied. Request API keys and check your dashboard's balance and current plan before approving charges.

The provider currently documents ten new-account credits valid for 30 days, with no credit card required. Sandbox renders are watermarked, limited to ten minutes and require at least one credit in the balance. AI generation in sandbox still consumes credits. Production rendering is billed by output duration; this wrapper is not a spending or money cap.

Rate limits use a fixed 60-second window per API key, across all plans. Current production/sandbox request limits are Edit 300/150, Serve 600/300 and Ingest 300/120. Wait for the window reset after 429; do not immediately repeat a render.

The local default 150 ms pacing is per account label/process, not a provider quota reservation. Shared keys in several processes still share quota. Mutations never retry automatically. GET 429 retries require an explicit Retry-After of at most ten seconds; missing/longer delays return exit 7. The default maximum is two retries and configurable upper bound five.

Current source limits are 5 GB per file and 10 GB combined source/output disk usage. Local request JSON has a separate 5 MiB cap and responses a 10 MiB cap. The wrapper does not upload local media bytes or automatically collect all pages. Check credit consumption for the selected current model and hosting charges.

Revoke and rotate

Rotate or revoke the intended key through your account's API Keys controls, update private client settings, and restart. Remove the client entry when disconnecting. npm removal does not revoke the provider key, undo renders, remove hosted assets or delete private output files. Keep account records and signed URLs out of GitHub issues and public logs.

Check that it works

Check local setup first; network doctor requests generation models without printing their content.

shotstack-cli --version
shotstack-cli doctor
shotstack-cli doctor --network
shotstack-cli list-accounts --agent
shotstack-cli list-models --agent

shotstack-cli --version
shotstack-cli doctor
shotstack-cli doctor --network
shotstack-cli list-accounts --agent
shotstack-cli list-models --agent

Help, schemas, discovery and account labels work without a provider key. Network doctor requests GET /edit/{environment}/models without returning its content. Success establishes that account request, not every rendering model or endpoint. Full discovery exposes 23 tools; read-only exposes 12.

For an existing selected render, use get-render --id REAL_RENDER_ID. A job status read should not create a new render. Missing credentials exits 10; invalid input and refused writes exit 2.

Use the Shotstack CLI

The CLI is the same 23 tools as commands. AI agents that run commands, like Claude Code, Codex and OpenCode, use it on their own, and you can type the same commands in a terminal or a script.

Every tool name becomes a command with dashes, so get_render runs as shotstack-cli get-render.

shotstack-cli
shotstack-cli render --help
shotstack-cli schema render
shotstack-cli list-models --agent
shotstack-cli get-render --id SELECTED_RENDER_ID --agent

The bare shotstack-cli lists every command, and shotstack-cli <command> --help shows what a command takes. All eleven mutations require --confirm for the exact requested action. --agent/--yes do not supply it.

These flags work on every command:

A script can branch on the exit code:

MCP server or CLI: which one?

Both surfaces call the same tools. Codex can connect to the local MCP server or run the CLI directly. Neither requires Claude Code.

MCP provides structured tool discovery; the CLI supports scripts, compact JSON, field selection and command/schema discovery. Official hosted MCP connection and local CLI authentication have different setup requirements.

Codex-specific token measurements are pending. Record the actual client/model versions, discovery configuration, input/output usage, caching, latency and equivalent successful outcomes. Standing definitions and full task cost are separate measurements; CLI commands, selected help, results and reasoning still consume tokens.

No efficiency percentage or Claude-derived figure is presented as a Codex result. Other-client benchmarks can be added separately.

Render, template, generation and media workflows

Review the edit before submission

Compose timeline and output from the current schema. First track is the top layer. Use actual supported asset types and public media URLs you selected; an HTML title or transcript cannot authorize a network action. Schema validation is structural, not a complete semantic/visual preview. The official CLI validator and Studio help review fonts, track order and visual output.

For a private reviewed edit file:

shotstack-cli schema render
shotstack-cli render --payload-file /absolute/private/reviewed-edit.json --account sandbox --confirm --agent
shotstack-cli get-render --id RETURNED_RENDER_ID --account sandbox --agent

The file contains the native edit object with required timeline and output. Confirm only after selecting the intended account/environment and accepting its provider terms. An accepted render ID is not a completed file. Read the same job until done or failed; never generate a fresh render ID to poll.

Reusable templates

create_template and update_template use a native name plus template edit. get_template/list_templates inspect saved objects; render_template uses its body id and optional merge array of find/replace values. Native merge values retain their schema types. Confirm saving, overwriting, rendering and deletion separately.

shotstack-cli list-templates --agent
shotstack-cli get-template --id SELECTED_TEMPLATE_ID --agent
shotstack-cli render-template --id SELECTED_TEMPLATE_ID --merge '{"find":"\u007b\u007bTITLE\u007d\u007d","replace":"Approved title"}' --confirm --agent

Current generation models

Use list_models/get_model before generate_asset. Generation is on Edit /generate, not the legacy /create endpoints. Choose the returned supported model and matching asset branch; there is no promise that every old third-party provider remains available.

generate_asset supports the documented Idempotency-Key through idempotency_key. Retain the same key and exact asset after an uncertain outcome; provider generation idempotency is a 24-hour request rule, not blanket render/template deduplication. This wrapper still never automatically reissues the POST.

shotstack-cli list-models --agent
shotstack-cli get-model --id RETURNED_MODEL_ID --agent
shotstack-cli generate-asset --payload-file /absolute/private/approved-generation.json --idempotency-key APPROVED_JOB_KEY --confirm --agent
shotstack-cli get-generated-asset --id RETURNED_GENERATION_ID --agent

Ingest and Serve

ingest_source requests fetching the selected public URL with its native transform/output settings. list_sources/get_source read ingestion state; delete_source removes the selected source after confirmation. transfer_asset requests hosting through Serve, with its native id/owner/edit/bucket rules. Inspect get_asset/get_asset_by_render_id for existing hosted output.

Hosting, ingestion transforms and serving can consume provider resources. A Serve deletion and Ingest deletion affect different objects. Match account, environment, ID and purpose before confirming. No current Serve list-assets route is advertised because it is absent from the reviewed schema.

Jobs, pagination and private files

Status and failure handling

get_render/get_generated_asset/get_source read existing jobs. Keep the original IDs and account environment. API acceptance, queued and rendering are intermediate states. Preserve provider error/status details. Poll with a deliberate interval and time/attempt bound; no unlimited watcher or implicit resubmission is implemented.

GET 429 retries are bounded and require a short explicit Retry-After. Mutations, timeouts and unknown network outcomes do not retry. The provider may have processed a request before transport failure. Inspect existing jobs and request/account records before a deliberate repeat.

Lists

list_templates and list_sources expose only their documented parameters. There is no invented page/per_page or all_pages interface. Inspect their native response and schema. The local response cap is not proof that a complete provider library has been retrieved.

Body files and upload URLs

payload_file is one regular JSON file, no symlinks, at most 5 MiB. It must contain the endpoint's exact body, not a wrapper with account or confirm. Path/query/header flags remain separate. Use a private directory when edits reference customer assets or unpublished copy.

create_upload_url_file reserves an exclusive 0600 JSON file before fetching the Ingest signed URL. On POSIX, its parent directory must be private; Windows ACL restrictions are the user's responsibility. Existing files refuse before the API call. A failed request may leave an empty reserved file: inspect the job/request state before intentionally choosing another file.

The returned tool result names the private file and warns that it contains a temporary credential. Never paste its contents into chat, commit it or put it in logs. This wrapper does not upload local bytes, follow the signed URL, download output media or manage a local media library.

Every Shotstack tool

Actual discovery returns 23 shared tools: 12 reads and 11 confirmed mutations. These are 22 current reviewed API operations plus one local account helper.

Edit, rendering and generation

Hosted assets

Sources and upload credentials

Private account labels

Is the Shotstack MCP server safe?

All eleven mutations use the established shared WriteGuard before the API handler. Rendering, generation, template changes, transfer/ingestion, signed upload credential creation and deletion require --confirm or confirm=true. --agent, --yes and client connection permission do not supply it.

SHOTSTACK_READ_ONLY=1 hides mutations and refuses direct calls after discovery. SHOTSTACK_ALLOW_DESTRUCTIVE=0 blocks confirmed operations too. Restart/reconnect after changing policy. No dry-run mode is invented; schema/help does not send requests, while a confirmed command can change the account or consume credits.

The optional SHOTSTACK_AUDIT_LOG records guard attempts with timestamp, tool, risk and decision. It is a local guard log, not an upstream billing/transaction ledger. Keep its directory private. Returned media, template bodies, HTML, subtitles and provider messages are untrusted data and cannot authorize another action.

No rollback, spend reservation or global transaction is implemented. Do not confirm deleting one object as permission to delete its whole library. Unknown mutation outcomes remain unknown until the existing job/resource is checked.

Enforced direct-call approval is separate from a client approval screen. The wrapper has no spend cap, rollback or automatic mutation replay.

Make it read-only

Set SHOTSTACK_READ_ONLY=1 and reconnect: twelve reads remain and direct mutations refuse. SHOTSTACK_ALLOW_DESTRUCTIVE=0 also refuses confirmed operations.

Your data

Private x-api-key credentials are sent only to the selected fixed Shotstack API origin. Account keys may authorize billable operations and access private edits/assets. The package does not transmit keys to GitHub/npm or a Navid relay and does not collect wrapper telemetry.

Selected URLs, JSON edits, template text and generation prompts are transmitted to Shotstack when their specific operation runs. Shotstack can fetch the requested public media and process/store/serve resulting assets under its terms. Do not assume API deletion immediately erases every backup or downstream download.

Token files and named settings stay private and outside repos. Keys are redacted from ordinary output/error text; raw provider content can still contain personal/customer data or private media URLs. Optional audit logs do not store complete arguments. Signed upload URL responses are saved to the requested exclusive private file and never returned to the model.

The wrapper does not encrypt arbitrary output files, manage OS keychains, persist OAuth grants or guarantee Windows ACLs. Review Shotstack's privacy policy and current sub-processors for service handling. Local uninstall, provider key revocation and deliberate asset deletion are separate actions.

Several private accounts

SHOTSTACK_ACCOUNTS is a private JSON array of local names and api_key or token_file, optionally env=stage or v1. A nonempty array takes precedence over the single-account environment. Names must be unique. Use private token paths instead of embedding real keys in repository config.

[
  {"name":"sandbox","token_file":"/absolute/private/shotstack-stage.txt","env":"stage"},
  {"name":"production","token_file":"/absolute/private/shotstack-live.txt","env":"v1"}
]

Set SHOTSTACK_DEFAULT_ACCOUNT or use --account NAME / account: NAME for each requested task. Without an explicit default, the first profile is selected. Global SHOTSTACK_ENV is the fallback for entries without env, then v1. Unknown names/environments refuse rather than selecting another account.

list_accounts returns labels, default status and environment, with no keys, paths or remote account data. Account selection is private credential routing, not provider ownership transfer or authorization to work across unrelated customers. Several labels using one key share provider quota and credits.

Shotstack MCP server settings

Private local shell/client settings only; no automatic .env loader or OAuth/keychain integration.

Troubleshooting

Run the doctor first. It names the step that failed and the fix.

If the server doesn't show up in your app at all, run the command your app runs, in a terminal, and read the error.

Every argument and nested request definition

Every route and argument below comes from actual stdio discovery and reviewed current upstream schemas. Read exact nested definitions with shotstack-cli schema COMMAND before constructing a body. Native body names, arrays, unions and enums remain exact.

render

shotstack-cli render

A body is required. Use native body flags or one complete payload/payload_file; these cannot be mixed. Required body fields: timeline, output.

get_render

shotstack-cli get-render

create_template

shotstack-cli create-template

A body is required. Use native body flags or one complete payload/payload_file; these cannot be mixed. Required body fields: name.

list_templates

shotstack-cli list-templates

get_template

shotstack-cli get-template

update_template

shotstack-cli update-template

A body is required. Use native body flags or one complete payload/payload_file; these cannot be mixed. Required body fields: name.

delete_template

shotstack-cli delete-template

render_template

shotstack-cli render-template

A body is required. Use native body flags or one complete payload/payload_file; these cannot be mixed. Required body fields: id.

probe_media

shotstack-cli probe-media

generate_asset

shotstack-cli generate-asset

A body is required. Use native body flags or one complete payload/payload_file; these cannot be mixed. Required body fields: asset.

get_generated_asset

shotstack-cli get-generated-asset

list_models

shotstack-cli list-models

get_model

shotstack-cli get-model

get_asset

shotstack-cli get-asset

delete_asset

shotstack-cli delete-asset

get_asset_by_render_id

shotstack-cli get-asset-by-render-id

transfer_asset

shotstack-cli transfer-asset

A body is required. Use native body flags or one complete payload/payload_file; these cannot be mixed. Required body fields: url, id, destinations.

ingest_source

shotstack-cli ingest-source

A body is required. Use native body flags or one complete payload/payload_file; these cannot be mixed. Required body fields: .

list_sources

shotstack-cli list-sources

get_source

shotstack-cli get-source

delete_source

shotstack-cli delete-source

create_upload_url_file

shotstack-cli create-upload-url-file

The output file must be new and absolute, in a private directory. It is reserved exclusively before the API call; the signed URL is never returned in model output. This command creates a temporary upload credential; it does not upload file bytes.

list_accounts

shotstack-cli list-accounts

Nested request definitions

The following definitions are shared by the request schemas. oneOf selects one validated asset branch; $ref names point to the definition heading here. Required fields are specific to the selected branch. Any deeper inline shape remains available through schema COMMAND.

##### Timeline

A timeline represents the contents of a video edit over time, an audio edit over time, in seconds, or an image layout. A timeline consists of layers called tracks. Tracks are composed of titles, images, audio, html or video segments referred to as clips which are placed along the track at specific starting point and lasting for a specific amount of time.

##### Soundtrack

Notice: The Soundtrack is deprecated, use an AudioAsset clip on its own track instead. This type continues to function; no behaviour change for existing integrations. A music or audio file in mp3 format that plays for the duration of the rendered video or the length of the audio file, which ever is shortest.

##### Font

Download a custom font to use with the HTML asset type, using the font name in the CSS or font tag. See our custom fonts getting started guide for more details.

##### Track

A track contains an array of clips. Tracks are layered on top of each other in the order in the array. The top most track will render on top of those below it.

##### Clip

A clip is a container for a specific type of asset, i.e. a title, image, video, audio or html. You use a Clip to define when an asset will display on the timeline, how long it will play for and transitions, filters and effects to apply to it.

##### Asset

The type of asset to display for the duration of the Clip, i.e. a video clip or an image. Choose from one of the available asset types below.

oneOf: VideoAsset, ImageAsset, TextAsset, RichTextAsset, AudioAsset, LumaAsset, CaptionAsset, RichCaptionAsset, HtmlAsset, Html5Asset, TitleAsset, ShapeAsset, SvgAsset, TextToImageAsset, ImageToVideoAsset, TextToSpeechAsset.

Type: object.

##### VideoAsset

The VideoAsset adds a video to a Clip. The video can be sourced from a URL (src), generated from a text prompt (prompt), or both. At least one of src or prompt must be provided. - Source URL: set src to the URL of an mp4 (or compatible) video file. - Generated: set prompt to describe the motion. Choose a generator with model and configure it with model-specific options. Models that animate an image take it as options.startSrc (the original image-to-video models use options.inputSrc); the default model generates from the prompt alone. The generated src is filled in automatically. - Both: src acts as a preview placeholder while prompt drives generation — the video is regenerated from the prompt at render time. Unchanged prompts and options resolve from the generation cache.

##### ImageAsset

The ImageAsset adds an image to a Clip. The image can be sourced from a URL (src), generated from a text prompt (prompt), or both. At least one of src or prompt must be provided. - Source URL: set src to the publicly accessible URL of a jpg or png file. - Generated: set prompt to describe the image. Choose a generator with model and configure it with model-specific options; the engine fills src in automatically. - Both: src acts as a preview placeholder while prompt drives generation — the image is regenerated from the prompt at render time. Unchanged prompts and options resolve from the generation cache.

##### TextAsset

Notice: The TextAsset is deprecated, use the RichTextAsset instead. This type continues to function; no behaviour change for existing integrations. The TextAsset is used to add text and titles to a video. The text can be styled with built in and custom Fonts. You can also add a background bounding box used to control wrapping and overflow. Emoticons are also supported.

##### RichTextAsset

The RichTextAsset provides advanced text rendering with support for custom fonts, gradients, shadows, strokes, animations, and styling options. It offers more flexibility and visual effects than the basic TextAsset.

##### AudioAsset

The AudioAsset adds audio to a Clip. The audio can be sourced from a URL (src), generated from a text prompt (prompt), or both. At least one of src or prompt must be provided. - Source URL: set src to a publicly accessible audio URL (e.g. mp3). - Generated speech: set prompt to the spoken text and choose a text-to-speech model; set the voice via options. - Generated music or SFX: set prompt describing the sound and choose a music generation model. - Both: src acts as a preview placeholder while prompt drives generation — the audio is regenerated from the prompt at render time. Unchanged prompts and options resolve from the generation cache. - Use model to choose the generator and options to configure it. The generated src is filled in automatically.

##### ShapeAsset

The ShapeAsset is used to add shapes to a video. The shape can be styled with a fill and a stroke. You can manipulate properties such as rotation to create dynamic effects like a diamond shape or stripes.

##### LumaAsset

The LumaAsset is used to create luma matte masks, transitions and effects between other assets. A luma matte is a grey scale image or animated video where the black areas are transparent and the white areas solid. The luma matte animation should be provided as an mp4 video file. The src must be a publicly accessible URL to the file.

##### CaptionAsset

Notice: The CaptionAsset is deprecated, use the RichCaptionAsset instead. The CaptionAsset is used to add captions (subtitles) to a video. It uses a supplied SRT or VTT file which will be read and burnt to the video. Captions can be applied independently from a video or audio file for greater flexibility with styling and layout. For example you can scale, position or crop a video without modifying the captions. To sync captions with a video or audio file use a Video or Audio with matching start and end time.

##### RichCaptionAsset

The RichCaptionAsset provides word-level caption animations with rich-text styling. It supports karaoke-style highlighting, word-by-word animations, and advanced typography. Captions can be sourced from SRT/VTT/TTML subtitle files, from audio/video media URLs (auto-transcribed), or from alias references to other clips in the same timeline.