# io.github.GarAlex/promoshot (oci · ghcr.io/garalex/promoshot-mcp:v0.2.78)

Headless MCP: author and render PromoShot .promo video projects (stills, GIFs, video).

- Trust score: 40/100 (low)
- Change this week: +5
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-09-21

## Components

- oci · `ghcr.io/garalex/promoshot-mcp:v0.2.78`: 40/100 (this document), [markdown](https://verifymcp.io/servers/garalex-promoshot/ghcr-io-garalex-promoshot-mcp-v0-2-78.md), [page](https://verifymcp.io/servers/garalex-promoshot/ghcr-io-garalex-promoshot-mcp-v0-2-78)

## Channel facts

- Registry: `oci`
- Package: `ghcr.io/garalex/promoshot-mcp:v0.2.78`
- Transport: `stdio`

## Trust breakdown

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. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-09-21.

- **Supply Chain Security**: 0/100
  - Malware scan not yet available for this package.
  - Known CVEs could not be checked: this artifact ships no SBOM, so there is no dependency list to read. Publishing one would let us assess it.
  - Install-script risk not yet assessed.
  - Dependency health could not be checked: this artifact ships no SBOM, so there is no dependency list to read. Publishing one would let us assess it.
- **Provenance & Transparency**: 32/100
  - Source repository is publicly reachable at the declared URL.
  - Provenance check failed: no build-provenance attestation is published.
  - License check failed: no license is declared.
  - Actively maintained (last published 10 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 65/100
  - AI-judged instruction clarity (good).
  - Context-footprint check failed: tool/resource definitions use about 4122 tokens (~158/item across 26 items; 26 tools + 0 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 33/100
  - Stability observed for 10 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 92/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 76% of tool parameters carry a description.
- **Tool Safety**: 100/100
  - No prompt-injection markers were found in the server instructions, tool names or descriptions we captured.
  - We read all 26 captured tool definition(s), and no name or description among them implies an irreversible operation.
  - An AI judge read all 27 captured unit(s) of tool text and found none that tries to manipulate the model reading it.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

**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

### How do I install the io.github.GarAlex/promoshot MCP server?

io.github.GarAlex/promoshot runs locally as a container image, launched with docker run --rm -i ghcr.io/garalex/promoshot-mcp:v0.2.78. Ready-made configuration for Claude, Cursor, VS Code, Codex and 3 more is on this page, copied from each client's own documentation.

### Claude

```bash
claude mcp add garalex-promoshot -- docker run --rm -i ghcr.io/garalex/promoshot-mcp:v0.2.78
```

### Cursor

```json
{
  "mcpServers": {
    "garalex-promoshot": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "ghcr.io/garalex/promoshot-mcp:v0.2.78"
      ]
    }
  }
}
```

### VS Code

```json
{
  "servers": {
    "garalex-promoshot": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "ghcr.io/garalex/promoshot-mcp:v0.2.78"
      ]
    }
  }
}
```

### Codex

```bash
codex mcp add garalex-promoshot -- docker run --rm -i ghcr.io/garalex/promoshot-mcp:v0.2.78
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "garalex-promoshot": {
      "type": "local",
      "command": [
        "docker",
        "run",
        "--rm",
        "-i",
        "ghcr.io/garalex/promoshot-mcp:v0.2.78"
      ],
      "enabled": true
    }
  }
}
```

### Hermes

```yaml
mcp_servers:
  garalex-promoshot:
    command: "docker"
    args: ["run", "--rm", "-i", "ghcr.io/garalex/promoshot-mcp:v0.2.78"]
```

### Netclaw

```json
{
  "McpServers": {
    "garalex-promoshot": {
      "Transport": "stdio",
      "Command": "docker",
      "Arguments": [
        "run",
        "--rm",
        "-i",
        "ghcr.io/garalex/promoshot-mcp:v0.2.78"
      ]
    }
  }
}
```

### Other

```json
{
  "mcpServers": {
    "garalex-promoshot": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "ghcr.io/garalex/promoshot-mcp:v0.2.78"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-09-20 (score 40, +1)

No change was recorded against any check on this day. Stability & Change Management went from 27 to 30. That category is still filling its 30-day observation window: 8 days of observed history at the previous scan, 9 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-09-18 (score 39, +4)

- [functional improvement] Stability: unverified → 0.23

### 2026-09-17 (score 35, 0)

- [functional regression] Security disclosure: unverified → fail

### 2026-09-16 (score 35, 0)

- [functional regression] Security disclosure: fail → unverified

### 2026-09-11 (score 35)

First indexed and scored.

## MCP tools (26)

### `promo_validate` (~98 tokens)

Decode a project with the renderer's own parser and report everything it would silently correct. 'ok' means it will render. A mid-composition thumbnail comes attached — glance at it.

Input parameters:

- `preview` (boolean): Attach an inline thumbnail of the composition (default true); the same image lands at <Name> Exports/preview.png beside the project
- `project` (string, required): Path to the .promo project folder (metadata.json + Resources/)

### `promo_inspect` (~47 tokens)

Canvas, duration, layers by kind, undefined colours, and any layer whose media is missing.

Input parameters:

- `project` (string, required): Path to the .promo project folder (metadata.json + Resources/)

### `promo_schema` (~39 tokens)

The authoring subset of the .promo format plus four complete, validated recipes. Read this once before authoring; promo_schema_full is the whole format.

### `promo_schema_types` (~47 tokens)

The format as a JSON Schema, types only, GENERATED from the parser's own structs — fill a structured object against this instead of freehanding JSON; the prose lives in promo_schema.

### `promo_schema_full` (~120 tokens)

The whole .promo format, from the same single file the engine compiles in — sprites, masks, motion paths, duration rules, waits, gradients, palette roles and all. 67 KB whole: pass `topics` to take only what this piece needs.

Input parameters:

- `topics` (array): "core" for the format proper, and a feature word for its section: composition, markers, audio, chroma, pointer, effects, lut, model, particles, route, morph, parts, recipe, environment, stage. Omit f…

### `promo_render_still` (~138 tokens)

Render one PNG at a moment. Returns the path written, never the bytes.

Input parameters:

- `out` (string): Output file (default: <Name> Exports/still-<time>s.png beside the project)
- `project` (string, required): Path to the .promo project folder (metadata.json + Resources/)
- `proxy` (string): auto (default) reads a built tier-1 proxy when the output fits it; on builds missing proxies first; off never reads one. A full-size render never does.
- `size` (string): WxH (default: canvas)
- `time` (number): Seconds (default 0)

### `promo_render_frames` (~289 tokens)

LOOK at the composition: moments rendered to PNGs and tiled into one contact sheet, attached to this reply as an image. Bare, it samples 12 moments across the whole piece — the fastest way to catch an off-centre card, an empty frame or a mis-aimed viewport. Name `times` for exact moments, or a from/to/fps range for every frame in it (240 at most). Frames from this tool's own previous call in the same folder are replaced, never mixed.

Input parameters:

- `fps` (number): Every frame at this rate over the range — an export, not a look
- `from` (number)
- `outDir` (string): Output directory (default: <Name> Exports/frames beside the project)
- `project` (string, required): Path to the .promo project folder (metadata.json + Resources/)
- `proxy` (string): auto (default) reads a built tier-1 proxy when the output fits it; on builds missing proxies first; off never reads one. A full-size render never does.
- `sample` (integer): How many moments to spread across the range (default 12 when neither times nor a range is given)
- `size` (string): WxH (default: canvas)
- `times` (array): Exact seconds to render — the sheet's cells follow this order
- `to` (number)

### `promo_render_video` (~197 tokens)

Render the mp4, audio mixed — needs ffmpeg on PATH. Returns the path written.

Input parameters:

- `alpha` (boolean): Render over nothing and keep the frames' alpha — ProRes 4444 in a .mov.
- `codec` (string): h264 in an mp4 (default); ProRes 422 HQ or 4444 want a .mov out path.
- `fps` (number): Default: the project's own, else 30
- `out` (string): Output file (default: <Name> Exports/export.mp4 beside the project)
- `project` (string, required): Path to the .promo project folder (metadata.json + Resources/)
- `proxy` (string): auto (default) reads a built tier-1 proxy when the output fits it; on builds missing proxies first; off never reads one. A full-size render never does.
- `size` (string): WxH (default: canvas)

### `promo_render_gif` (~139 tokens)

Render a looping GIF — the preview format, needing no ffmpeg. Default 12fps. Returns the path written.

Input parameters:

- `fps` (number): Default 12
- `out` (string): Output file (default: <Name> Exports/export.gif beside the project)
- `project` (string, required): Path to the .promo project folder (metadata.json + Resources/)
- `proxy` (string): auto (default) reads a built tier-1 proxy when the output fits it; on builds missing proxies first; off never reads one. A full-size render never does.
- `size` (string): WxH (default: canvas)

### `promo_proxy` (~83 tokens)

Build tier-1 proxies (960 px long edge, every frame a keyframe) for every video resource in a project, in the proxy cache outside the package. Stills, frames and small renders then read them by default (proxy: auto) — what makes an hour-long 4K source scrub and render like a short one.

Input parameters:

- `project` (string, required)

### `promo_workspace` (~26 tokens)

The folder this machine keeps assistant-authored projects in. Create new .promo folders here.

### `promo_media_probe` (~127 tokens)

The facts of one source file or SEVERAL, before composing with them: container, duration, streams — codec, size, fps, display rotation, channels. Distilled JSON, not ffprobe's firehose. Each answer carries the `resource` entry that file becomes, ready to paste into `resources` with its pixel size already measured — which is what a `placement` rule needs to resolve against anything other than a square.

Input parameters:

- `file` (string): One path
- `files` (array): Several paths at once; the answer is keyed by the path asked for

### `promo_media_turntable` (~106 tokens)

Eyes on a model: a .glb rendered from N yaws round it, tiled into one PNG contact sheet with each cell's yaw. Look at this before choosing a camera for a model layer. (`promo_media_probe` on a .glb names its material slots, clips and bounds.)

Input parameters:

- `count` (integer)
- `file` (string, required)
- `out` (string)
- `size` (integer): cell size in px (default 320)

### `promo_media_filmstrip` (~86 tokens)

Eyes on the footage: N evenly spaced frames tiled into one PNG contact sheet, sampled times returned so a cell maps to a moment. Look at this before deciding what a clip shows.

Input parameters:

- `count` (number): Frames (default 12, max 48)
- `file` (string, required)
- `out` (string): Output PNG (default: the workspace folder)

### `promo_media_silences` (~76 tokens)

Ears on the footage: where the sound is NOT — silence spans and their inverse, the sound spans an edit actually wants. Cuts and captions land on these boundaries.

Input parameters:

- `file` (string, required)
- `minSeconds` (number): Default 0.35
- `thresholdDb` (number): Default -35

### `promo_media_scenes` (~89 tokens)

Eyes for CUTS: per-frame scene-change scores distilled to cut times and the shots between them — the footage-first answer when a clip has no silence gaps to cut on. Scores are ffmpeg's scene score (0..1, motion-suppressed); 0.4 catches hard cuts.

Input parameters:

- `file` (string, required)
- `threshold` (number): Default 0.4

### `promo_transcribe` (~65 tokens)

Ears for WORDS: a transcript with timings, the draft captions are cut from. Headless this needs whisper.cpp's whisper-cli on PATH and WHISPER_MODEL set; without them an agent cannot transcribe and the refusal says so.

Input parameters:

- `file` (string, required)

### `promo_init` (~210 tokens)

Create a project folder: metadata.json boilerplate, canvas, palette, a background layer, ids minted. The file it writes is ordinary metadata.json — hand-edit it freely afterwards; the schema stays the source of truth. Never overwrites. A thumbnail comes attached.

Input parameters:

- `canvas` (string, required): "1920x1080" (or {width, height})
- `id` (string): Your own short project id; unnamed mints a UUID. The background layer is always "bg".
- `name` (string)
- `palette` (object): Named colours: {"canvas": "10182B", "text": "F3F5FF"} (or [{name, colorHex}]). "canvas" becomes the background.
- `preview` (boolean): Attach an inline thumbnail of the composition (default true); the same image lands at <Name> Exports/preview.png beside the project
- `project` (string, required): Path to the .promo project folder (metadata.json + Resources/)

### `promo_upsert_layer` (~488 tokens)

SCAFFOLD one layer — image, video or caption — with a placement, a fadeIn, a device/border frame. Media is copied in, sizes and durations probed, the composition re-stretched every call. Pass an existing id to UPDATE: only the fields you pass change, placement merges into the first keyframe, hand-added keyframes survive. This is the scaffold, not the whole format: motion and viewport ride promo_upsert_keyframe; transitions beyond fadeIn are ordinary JSON edits — start from a promo_schema recipe. A thumbnail sampled at the touched layer's midpoint comes attached — LOOK at it before the next edit.

Input parameters:

- `captionText` (string)
- `duration` (number): Seconds (default: a video's own length, else 3)
- `fadeIn` (number): Seconds
- `file` (string): Image/video to copy in — required to create, optional on update (a repoint)
- `fontSize` (number): Caption points
- `frame` (object): Resource dressing: {kind: "device"|"border", material, tiltY, borderWidth, cornerRadius} — define @edge in the palette when you frame
- `id` (string): An existing layer's id makes this an UPDATE; on create, your own short id ("card") is used verbatim
- `kind` (string, required)
- `lineHeight` (number): Line spacing as a multiple of font size (default 1.25); ~1.05 for a stacked headline
- `name` (string)
- `placement` (object): {height|width|mode, anchor, offset} — media sizes too; a caption takes anchor and offset only
- `preview` (boolean): Attach an inline thumbnail of the composition (default true); the same image lands at <Name> Exports/preview.png beside the project
- `project` (string, required): Path to the .promo project folder (metadata.json + Resources/)
- `resourceId` (string): Your own short id for the created resource; unnamed mints a UUID
- `startTime` (number)
- `tracking` (number): Letter spacing in points — open a small eyebrow out (+6), tighten a big headline (-1.4)
- `weight` (string): The face's weight; heavier than bold is where a store headline lives

### `promo_upsert_keyframe` (~347 tokens)

MOTION in the format's own language: create or merge ONE keyframe on a layer. A second placement keyframe is a push-in, viewport keyframes are a Ken Burns ride, colorHex ramps a background. Pass an existing keyframe id to UPDATE — only the fields you pass change. Creating without transitionDuration ramps from the previous keyframe (a stated 0 holds). Swaps, waits and motion paths stay ordinary JSON edits.

Input parameters:

- `colorHex` (string): Background layers only — ramps the colour
- `easing` (string)
- `fontSize` (number): Caption points
- `id` (string): An existing keyframe's id makes this an UPDATE; on create, your own short id ("k1") is used verbatim
- `layer` (string, required): The layer's id — promo_inspect lists them
- `opacity` (number)
- `placement` (object): {height|width|mode, anchor, offset} — a stored rule, re-resolved on every read
- `preview` (boolean): Attach an inline thumbnail of the composition (default true); the same image lands at <Name> Exports/preview.png beside the project
- `project` (string, required): Path to the .promo project folder (metadata.json + Resources/)
- `tiltX` (number)
- `tiltY` (number)
- `time` (number): Seconds, layer-local — required to create
- `transitionDuration` (number): Seconds of ramp INTO this keyframe
- `viewport` (array): [x, y, w, h] window onto the source, unit coordinates
- `zoom` (number)

### `promo_apply` (~225 tokens)

The whole vocabulary through one door: a batch of the editor's own commands applied as ONE atomic step — delete, move, rename, enable, retime; addLayer/addResource whole; updateLayer / patchResource / patchSettings as JSON merge patches (only the fields you pass change; null removes) — a wipe is {"transitionIn": {"kind": "wipe", "duration": 0.5}}, a swap is upsertKeyframe with resourceID and a transition, a trim is patchResource; setMarkers replaces the timeline's markers and chapters whole. Every command succeeds or nothing is written. The schema of `commands` IS the editor's Command enum.

Input parameters:

- `commands` (array, required): Commands in order; ids are the file's own (promo_inspect lists layers, resources by promo_schema_full)
- `preview` (boolean): Attach an inline thumbnail of the composition (default true); the same image lands at <Name> Exports/preview.png beside the project
- `project` (string, required): Path to the .promo project folder (metadata.json + Resources/)

### `promo_slideshow` (~274 tokens)

The wizard, for agents: pictures and clips in, a complete show out — the same arrangement the apps' wizard builds. kind classic (one slide at a time, crossfade by default), carousel (cards fly in and settle), or appStore (a store listing: your shots in one device frame over a background, a headline per shot, the canvas the store's own size). Creates the project folder and copies the media in; refine with the other tools afterwards. Never overwrites.

Input parameters:

- `backgroundColorHex` (string)
- `canvas` (string): "1920x1080" (ignored for appStore — the store decides)
- `device` (string): appStore: the frame and the store's canvas
- `direction` (string): Carousel
- `framing` (string)
- `kind` (string): Default classic
- `name` (string)
- `preview` (boolean): Attach an inline thumbnail of the composition (default true); the same image lands at <Name> Exports/preview.png beside the project
- `project` (string, required): Folder to create, e.g. <workspace>/Show.promo
- `sizing` (string)
- `slides` (array, required)
- `transition` (string): Default crossfade
- `transitionEdge` (string)

### `promo_explain` (~144 tokens)

The agent's debugger: why is this layer where it is — the renderer's OWN numbers at a moment. Per layer: visible and why not, the resource shown (swap-aware), the resolved transform and the rect on the canvas in pixels, opacity, rotation, tilt, viewport, gain, the keyframes bracketing the moment, transitions and fades; per project: timing problems and validate's warnings. Defaults to the composition's midpoint.

Input parameters:

- `layer` (string): One layer's id; absent = all
- `project` (string, required): Path to the .promo project folder (metadata.json + Resources/)
- `time` (number): Seconds (default: midpoint)

### `promo_diff` (~100 tokens)

What changed since you last looked, in the format's own terms: two projects compared by entity — settings by key, resources and layers by id, keyframes by id — as lines you can act on. Copy metadata.json aside before a person's turn, then diff against the copy.

Input parameters:

- `against` (string, required): The other project folder (or its metadata.json)
- `project` (string, required): Path to the .promo project folder (metadata.json + Resources/)

### `promo_voices` (~112 tokens)

A narration provider's voices — id, name and a line of detail per voice (openai's fixed roster; elevenlabs and google list live) — with the person's own key: the OS keyring (`promoshot-mcp key set <provider>`), else a secrets file (OPENAI_API_KEY_FILE, or /run/secrets/OPENAI_API_KEY) where there is no keyring. Use before promo_speak to pick a voiceID.

Input parameters:

- `provider` (string): Default openai

### `promo_speak` (~213 tokens)

Synthesize narration for every resource whose speech.text says something, spending the PERSON'S OWN provider key from the OS keyring (`promoshot-mcp key set <provider>`) or, where there is none, a secrets file (OPENAI_API_KEY_FILE or /run/secrets/OPENAI_API_KEY), matching each script's provider (default openai/alloy). Unchanged text is reused by receipt, never billed twice. Keys are checked for EVERY pending narration before anything is bought, and each bought receipt is written back at once. Without a key an agent CANNOT narrate — record a voice file into Resources/ and reference it as an ordinary audio resource instead.

Input parameters:

- `check` (boolean): Spend nothing: report where each needed provider's key comes from (never the key) and what a real call would synthesize — ready, blocked, or nothing to do. With no project, the keys alone.
- `project` (string): Path to the .promo project folder (metadata.json + Resources/)

## Diagnostics

Captured diagnostic sections: Provenance. The full working is on the page: https://verifymcp.io/servers/garalex-promoshot/ghcr-io-garalex-promoshot-mcp-v0-2-78#diagnostics

## Score history

- 2026-09-21: 40
- 2026-09-20: 40
- 2026-09-19: 39
- 2026-09-18: 39
- 2026-09-17: 35
- 2026-09-16: 35
- 2026-09-15: 35
- 2026-09-14: 35
- 2026-09-13: 35
- 2026-09-12: 35
- 2026-09-11: 35

## Common questions

### What is the io.github.GarAlex/promoshot MCP server?

io.github.GarAlex/promoshot is an MCP server listed in the public MCP registry as io.github.GarAlex/promoshot. Headless MCP: author and render PromoShot .promo video projects (stills, GIFs, video). This page covers its container image (ghcr.io/garalex/promoshot-mcp:v0.2.78).

### Is the io.github.GarAlex/promoshot MCP server safe to use?

io.github.GarAlex/promoshot scores 40 out of 100 on VerifyMCP. That is a record of what we were able to check automatically, not an endorsement. The category breakdown on this page shows every signal behind the number, including the ones we could not confirm.

### What tools does the io.github.GarAlex/promoshot MCP server expose?

io.github.GarAlex/promoshot exposes 26 tools: promo_validate, promo_inspect, promo_schema, promo_schema_types, promo_schema_full, and 21 more. Their descriptions and schemas cost roughly 3,885 tokens of context every time the server is loaded.

### Is the io.github.GarAlex/promoshot MCP server still maintained?

io.github.GarAlex/promoshot is still listed as active in the MCP registry. We last reached this channel on 21 September 2026. Those dates come from our own scans of the registry and the channel itself, not from anything the publisher announced.

## Links

- Repository: https://github.com/GarAlex/promoshot
- Website: https://promoshot.app/mcp
- Changelog RSS feed: https://verifymcp.io/servers/garalex-promoshot/ghcr-io-garalex-promoshot-mcp-v0-2-78.xml
- Changelog JSON feed: https://verifymcp.io/servers/garalex-promoshot/ghcr-io-garalex-promoshot-mcp-v0-2-78.json
- HTML version of this page: https://verifymcp.io/servers/garalex-promoshot/ghcr-io-garalex-promoshot-mcp-v0-2-78