Promoshot
Headless MCP that authors and renders PromoShot video projects as stills, GIFs and MP4
- 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.7Add to claude_desktop_config.json
{
"mcpServers": {
"promoshot": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/garalex/promoshot-mcp:v0.4.7"
]
}
}
}Add to ~/.cursor/mcp.json
{
"mcpServers": {
"promoshot": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/garalex/promoshot-mcp:v0.4.7"
]
}
}
}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

HyperFrames by HeyGen
MCP serverHosted MCP connector for creating and rendering videos from HTML through AI chat
- Remote
- Freemium
- 85.3K GitHub stars
- Design and media

ffmpeg-skill
MCP serverLocal FFmpeg video and audio editing tools for coding agents over MCP
Runs locally- Open source
- 6.9K GitHub stars
- Design and media

Generate fictional character portraits and lip-synced talking videos from text over MCP
- 10 tools
- Remote
- Freemium
- Design and media

ChartAnt
MCP serverRemote MCP server returning charts, maps and dashboards as hosted PNG links
- 51 tools
- Remote
- Freemium
- Design and media

VfxSmith
MCP serverSearch, generate, refine and export pixel art game effects from Claude Code or Codex
Not checked yet- Remote
- Freemium
- Design and media

CalderFlow
MCP serverTurn notes or specs into editable flowcharts, timelines and funnels from an AI assistant
- 10 tools
- Remote
- Free
- Design and media