Skip to content
MCP server

Promoshot

Headless MCP that authors and renders PromoShot video projects as stills, GIFs and MP4

Runs locallyStatus and history
Install
Pricing
Open source
Platforms
macOS, Linux, CLI
Runs
Locally
Version
0.4.7
Listing updated
2 days ago

About Promoshot

Promoshot is an open-source MCP server for design and media. It runs locally on your machine and is started by your AI client.

This server lets an agent turn a product screenshot or screen recording into a share-ready promo without opening a GUI. The agent writes a .promo project, which is a folder holding metadata.json plus media, with layers, keyframed motion and a caption, optionally with a 2.5D device slab that adds bezel, depth, tilt and contact shadow. It validates first, then renders a still to check the look, and a GIF or video to share. Paths come back instead of bytes, and outputs land in the project's Exports folder.

The renderer is the same compositor as the Mac and iOS PromoShot apps, using wgpu, and on a Linux box with no GPU it falls back to bundled lavapipe. Video needs ffmpeg and ffprobe. The server's --workspace sets where new projects go and --root limits which folders it can touch.

The site notes agents will not find the repo alone, so it ships a SKILL.md for Claude, Grok and other agents; it also distinguishes this app from similarly named screenshot-to-video apps. Tools shown include promo_validate, promo_render_still and promo_render_video, and the README mentions promo_apply and promo_slideshow.

Install

Run in a terminal

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

Add to claude_desktop_config.json

{
  "mcpServers": {
    "promoshot": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/garalex/promoshot-mcp:v0.4.7"
      ]
    }
  }
}
Install in CursorOpens Cursor, which asks you to confirm. Or add it by hand:

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "promoshot": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/garalex/promoshot-mcp:v0.4.7"
      ]
    }
  }
}
Install in VS CodeOpens VS Code, which asks you to confirm. Or add it by hand:

Add to .vscode/mcp.json

{
  "servers": {
    "promoshot": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/garalex/promoshot-mcp:v0.4.7"
      ]
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json

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

Add to your client's MCP settings (most use this shape)

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

Tools this server provides (5)

Taken from the project documentation; the running server may differ.

promo_validate
Validate a .promo project before rendering.
promo_render_still
Render a still frame at a given time.
promo_render_video
Render the project to video.
promo_apply
Apply edit commands to a project.
promo_slideshow
Build a slideshow project.

What it does

Project authoring
Agents write .promo folders with layers, motion and captions.
Validate before render
promo_validate confirms a project will render.
Stills, GIFs and video
Render a still to check, then a GIF or MP4 to share.
2.5D device slab
Optional bezel, extruded depth, tilt and shadow baked at stage time.
Footage helpers
Probe, filmstrip, silence and scene-cut analysis for screen recordings.
Folder fencing
--root restricts which folders the server may touch.
No-GPU rendering
Bundled lavapipe lets Linux hosts render without a GPU.

Good for

  • Make a product card video from a screenshot
  • Cut a screen recording into a captioned promo
  • Render stills for a store listing from an agent
  • Build promo videos in CI on a headless Linux box
  • Create a looping GIF of a feature

Pricing

Open source

Open engine; the Mac and iOS app is sold separately on the App Store (price not listed)

Prices change. Check promoshot.app before you buy.

Promoshot FAQ

What does it need?

ffmpeg and ffprobe for video; Linux also wants a Vulkan driver such as mesa-vulkan-drivers unless the bundled lavapipe is used.

How do I run it?

Put promo and promoshot-mcp on your PATH, or use the ghcr.io/garalex/promoshot-mcp container, and register it with --workspace and --root.

Is it the same as other PromoShot apps?

No. The README says it is not the similarly named screenshot-to-template-video apps.

Does it return files directly?

It returns file paths under the project's Exports folder, not bytes.

Is Promoshot free?

Yes. Promoshot is open source, so you can use and self-host it for free.

How do I add Promoshot to Claude Code?

Run this command in your terminal: claude mcp add promoshot -- docker run -i --rm ghcr.io/garalex/promoshot-mcp:v0.4.7

What are the best alternatives to Promoshot?

The closest alternatives to Promoshot are HyperFrames by HeyGen, ffmpeg-skill, AvatarSay — Fictional Character & Talking Video MCP, ChartAnt and VfxSmith.

Alternatives to Promoshot

  1. Hosted MCP connector for creating and rendering videos from HTML through AI chat

    • Remote
    • Freemium
    • 85.3K GitHub stars
    • Design and media
  2. ffmpeg-skill

    MCP server

    Local FFmpeg video and audio editing tools for coding agents over MCP

    Runs locally
    • Open source
    • 6.9K GitHub stars
    • Design and media
  3. ChartAnt

    MCP server

    Remote MCP server returning charts, maps and dashboards as hosted PNG links

    • 51 tools
    • Remote
    • Freemium
    • Design and media
  4. VfxSmith

    MCP server

    Search, generate, refine and export pixel art game effects from Claude Code or Codex

    Not checked yet
    • Remote
    • Freemium
    • Design and media
  5. CalderFlow

    MCP server

    Turn notes or specs into editable flowcharts, timelines and funnels from an AI assistant

    • 10 tools
    • Remote
    • Free
    • Design and media