# Promoshot

> Promoshot is an open-source MCP server for design and media. Headless MCP that authors and renders PromoShot video projects as stills, GIFs and MP4. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** macOS, Linux, CLI
- **Website:** https://promoshot.app/mcp
- **Repository:** https://github.com/garalex/promoshot
- **MCP Registry name:** io.github.GarAlex/promoshot
- **Categories:** design and media
- **Listing updated:** 2026-11-14

## About

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`.

## Features

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

## Install

### Claude Code (Terminal)

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

### Claude Desktop (claude_desktop_config.json)

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

### Cursor (~/.cursor/mcp.json)

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

### VS Code (.vscode/mcp.json)

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

### Windsurf (~/.codeium/windsurf/mcp_config.json)

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

### Other clients (your client's MCP settings (most use this shape))

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

## Tools

- `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.

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

- [HyperFrames by HeyGen](https://ai-powered.com/mcp/hyperframes-by-heygen): HyperFrames by HeyGen is a freemium MCP server for design and media.
- [ffmpeg-skill](https://ai-powered.com/mcp/ffmpeg-skill): ffmpeg-skill is an open-source MCP server for design and media.
- [AvatarSay — Fictional Character & Talking Video MCP](https://ai-powered.com/mcp/avatarsay-fictional-character-and-talking-video-mcp): AvatarSay — Fictional Character & Talking Video MCP is a freemium MCP server for design and media.
- [ChartAnt](https://ai-powered.com/mcp/chartant): ChartAnt is a freemium MCP server for design and media.
- [VfxSmith](https://ai-powered.com/mcp/vfxsmith): VfxSmith is a freemium MCP server for design and media.
- [CalderFlow](https://ai-powered.com/mcp/calderflow): CalderFlow is a free MCP server for design and media.
- [Hourlore](https://ai-powered.com/mcp/hourlore): Hourlore is a freemium MCP server for design and media.
- [Eikino](https://ai-powered.com/mcp/eikino): Eikino is a freemium MCP server for security.

---
Source: https://ai-powered.com/mcp/promoshot
