Frames screenshots and screen recordings in realistic Apple device mockups for iPhone, iPad, Mac, and Apple TV.
Also known as cwooddgr/bezelbub, bezelbub, @dgr_labs/bezelbub-mcp
- Stars
- 9
- Tools
- —
- Downloads, 30 days
- 367
- Latest version
- 1.6.0
- Last commit
- Oct 20, 2026
- License
- —
What is Bezelbub MCP?
Bezelbub frames screenshots and screen recordings in realistic Apple device mockups for iPhone, iPad, Mac, and Apple TV.
Summary generated from the project's README
About Bezelbub MCP server
Bezelbub provides a way to place screenshots and screen recordings into realistic Apple device mockups. It supports a wide range of hardware including iPhone, iPad, Mac, and Apple TV. Users can interact with the service through a macOS and iOS application, a Swift package named BezelbubKit, or a headless command-line tool designed specifically for shell scripts, CI pipelines, and AI agents.
The command-line interface is built for programmatic use without interactive prompts. It features automatic device detection based on pixel dimensions or aspect ratios, allowing it to identify specific models like the iPhone 16 Pro or MacBook Air. Developers can specify colors, orientations, and output sizes for their assets. The tool also handles complex video tasks, such as exporting HEVC-with-alpha MOV files for transparent backgrounds or generating VP9/WebM copies for web compatibility via ffmpeg.
Because it is designed for automation, the CLI provides structured JSON output and specific exit codes to help agents handle errors. If a device cannot be identified, the system suggests the nearest matches by aspect ratio to facilitate automated corrections.
What you can do with it
- 1Automated device mockup generationAn AI agent can automatically frame a screenshot by detecting the correct device from its pixel dimensions.
- 2Creating transparent web videosA developer can generate a screen recording with a transparent background to overlay on websites.
- 3CI/CD visual asset pipelinesIntegrate device framing into a continuous integration pipeline using the headless command-line tool.
- 4Programmatic error handling for agentsAn AI client can use specific exit codes to determine why a framing command failed and attempt a fix.
Written from the project's README. Every use case is checked against a quote from it.
How to install Bezelbub MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Bezelbub MCP in Claude Code
$ claude mcp add bezelbub -- npx -y @dgr_labs/bezelbub-mcpInstall Bezelbub MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"bezelbub": {
"command": "npx",
"args": [
"-y",
"@dgr_labs/bezelbub-mcp"
]
}
}
}Install Bezelbub MCP in VS Code
.vscode/mcp.json
{
"servers": {
"bezelbub": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@dgr_labs/bezelbub-mcp"
]
}
}
}Install Bezelbub MCP in VS Code CLI
$ code --add-mcp '{"name":"bezelbub","type":"stdio","command":"npx","args":["-y","@dgr_labs/bezelbub-mcp"]}'Install Bezelbub MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"bezelbub": {
"command": "npx",
"args": [
"-y",
"@dgr_labs/bezelbub-mcp"
]
}
}
}Install Bezelbub MCP in Codex
$ codex mcp add bezelbub -- npx -y @dgr_labs/bezelbub-mcpInstall Bezelbub MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.bezelbub] command = "npx" args = ["-y", "@dgr_labs/bezelbub-mcp"]
Install Bezelbub MCP in Gemini CLI
$ gemini mcp add -s user bezelbub npx -- -y @dgr_labs/bezelbub-mcpInstall Bezelbub MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"bezelbub": {
"command": "npx",
"args": [
"-y",
"@dgr_labs/bezelbub-mcp"
]
}
}
}Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work · What to fix for more points
- Source repository linked and reachablecwooddgr/bezelbub is public and reachablegithub.com/cwooddgr/bezelbub ↗Pass
- Package names this repository as its source@dgr_labs/bezelbub-mcp names cwooddgr/bezelbub as sourcenpmjs.com/package/@dgr_labs/bezelbub-mcp ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)No licenseFinding
- Commit or release in the last yearLast commit or release 2026-10-20github.com/cwooddgr/bezelbub ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @dgr_labs/bezelbub-mcpPass
- No critical advisory in the package or its dependencies99 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubBezelbub
Bezelbub puts your screenshots and screen recordings inside realistic Apple device bezels, so you get pixel-accurate device mockups for iPhone, iPad, Mac, and Apple TV as framed images and videos. You can use it three ways:
- As a macOS and iOS app. Drop in a screenshot or a video, and Bezelbub picks the matching device and frames it.
- As a headless command-line tool,
bezelbub(brew install cwooddgr/tap/bezelbub). Frame a screenshot from a script, add a device frame to a screen recording, or export a transparent HEVC-with-alpha video with a VP9/WebM copy for Chrome and Firefox. We built it for shell scripts, CI, and AI agents. Jump to the CLI docs. - As a Swift package with no UI,
BezelbubKit, if you want the framing engine inside your own tool.
Get Bezelbub on the App Store for Mac, iPhone, and iPad.
What you can do with it
- Let it find the device. Drop in a screenshot or video and you get the right bezel. We recognize iPhones and iPads by their exact resolution. For Macs, iMac, Studio Display, and Apple TV we recognize the capture size of each macOS display zoom setting, from "Larger Text" to "More Space", so you can take the capture at any zoom level. If we don't have a size on file, we fall back to matching by aspect ratio. When several models share a panel, you pick from all of them. Load another screenshot for the same device and your device and color choices stay put.
- Drag and drop on the Mac. Drop a screenshot or screen recording on the window or the Dock icon.
- Paste on the Mac. Copy a screenshot and press ⌘V, or use Edit ▸ Paste.
- Photos and the share sheet on iPhone and iPad. Import from Photos, or send an image to Bezelbub from any app's share sheet.
- Frame videos. Export MOV and MP4 screen recordings with the bezel on top, with the audio kept.
- Export transparent video. Save a framed recording with a fully transparent background as HEVC-with-alpha in a QuickTime
.mov, ready to lay over any web page or presentation. - Fix rotation. Rotate a video that came in sideways. Option-click to go the other way.
- Pick the color. Every color Apple ships for each device.
- Set the export size. Change the width, the height, or the scale before saving. Images go up to 16,384 px and videos up to 7,680 px.
- Copy or save. Copy a framed image to the clipboard, save it as PNG, or export a framed video as MOV or MP4.
- Portrait or landscape for iPhone and iPad.
Devices
- iPhone: 14, 14 Plus, 14 Pro, 14 Pro Max, 15, 15 Plus, 15 Pro, 15 Pro Max, 16, 16 Plus, 16 Pro, 16 Pro Max, 17, 17 Pro, 17 Pro Max, Air, 18 Pro, 18 Pro Max
- iPhone Duo: three views, each its own device. Frame the inner display with the phone open (
iphoneduo), the outer display with the phone closed (iphoneduoouter), or the outer display with the phone open and seen from the back (iphoneduoouteropen), in portrait or landscape - iPad: iPad, iPad (A16), iPad Air 11"/13" M2, iPad Air 11"/13" M4, iPad mini, iPad mini (A17 Pro), iPad Pro 11"/13" M4, iPad Pro 11"/13" M5
- Mac: MacBook Air 13", MacBook Air 13"/15" M5, MacBook Pro 14", MacBook Pro 16", MacBook Pro 14"/16" M5, MacBook Neo, iMac 24", iMac 24" M4, Studio Display (2026). Any display zoom setting works. The Studio Display bezel covers the XDR too, because Apple ships identical art for both
- Apple TV: Apple TV 4K, from 1080p or 4K screenshots
The bezelbub command-line tool
With bezelbub you can frame screenshots and screen recordings from a shell script, a CI pipeline, or an AI agent. There is no GUI and nothing ever prompts you. Every input is a flag with a sensible default, you can ask for JSON output, and when something goes wrong you get a distinct nonzero exit code plus a concrete suggestion on stderr (valid ids, matching devices, nearest screen sizes), so one failed call tells you how to fix the next one.
Install it with Homebrew:
brew install cwooddgr/tap/bezelbub
Quick start
# Frame a screenshot. We detect the device from its pixel size.
bezelbub frame --input shot.png # writes shot-framed.png
# Frame a screen recording (.mov/.mp4/.m4v). Audio is kept; you get an MP4.
bezelbub frame --input demo.mp4 # writes demo-framed.mp4
# Transparent video: HEVC-with-alpha in a QuickTime .mov
# (plays in Safari and Apple frameworks; the background is fully transparent)
bezelbub frame --input demo.mp4 --background transparent # writes demo-framed.mov
# Add a VP9/WebM copy with alpha for Chrome and Firefox (needs ffmpeg on PATH)
bezelbub frame --input demo.mp4 --background transparent --webm
# writes demo-framed.mov and demo-framed.webm
# List device ids, colors, and screen sizes
bezelbub devices [--json]
# Which devices fit this screenshot or recording?
bezelbub devices --input shot.png # or demo.mp4, or --dimensions 1206x2622
# Or spell everything out
bezelbub frame --input shot.png --device iphone17pro \
--color "Cosmic Orange" \
--orientation landscape \
--background "#1D1D1F" \
--output-size 50% \
--output framed.png --json
frame is the default subcommand, so bezelbub --input shot.png works too.
How device detection works
Leave out --device and we work out the device from the input's pixel dimensions. For iPhones and iPads that means an exact match on screen resolution, within a pixel. For Macs, iMac, Studio Display, and Apple TV it means an exact match on capture size: every macOS display zoom setting captures at a known pixel size per model, so a 3420×2214 screenshot can only have come from a 15" MacBook Air, whatever zoom it was taken at. Sizes we don't have on file, such as external monitors or downscaled recordings, fall back to aspect-ratio matching. When you frame a display capture, we scale it to fit the bezel's screen.
Detection succeeds when exactly one device matches. If several models share the size, the error lists them so you can run again with --device <id>. If nothing matches, we suggest the nearest devices by aspect ratio. To check before framing anything, run bezelbub devices --input <path> or bezelbub devices --dimensions WxH.
Transparent video and WebM
Pass --background transparent with a video input and you get HEVC with an alpha channel in a QuickTime .mov instead of an MP4: a device-framed recording with a fully transparent background, ready to lay over anything. Safari and Apple's frameworks (AVFoundation, AppKit, UIKit) play HEVC-with-alpha. Chrome and Firefox don't decode it.
For those browsers, add --webm and you also get a VP9/WebM copy that keeps the alpha channel. To make it we render a temporary ProRes 4444 master and hand that to ffmpeg, which must be on your PATH. We deliberately don't hand ffmpeg the HEVC .mov: ffmpeg builds older than 8.0 can't decode HEVC's alpha layer and silently write an opaque WebM. Version 8 and later decode it fine, but the ProRes route works on any build. Serve both files, with the .mov first:
<video autoplay loop muted playsinline>
<source src="demo-framed.mov" type="video/quicktime" />
<source src="demo-framed.webm" type="video/webm" />
</video>
The order matters. Safari can play VP9/WebM but drops its alpha channel, so if you list the WebM first, Safari shows your transparency as solid black. With the .mov first, Safari takes the HEVC-alpha file, while Chrome and Firefox skip video/quicktime and fall through to the WebM.
If you pass --output for a transparent export, the path must end in .mov. The WebM lands beside it with a .webm extension.
Flags
bezelbub frame --input <path> [options]
bezelbub devices [--input <path> | --dimensions WxH] [--json]
Options for frame:
| Flag | What it does |
|---|---|
--input, -i |
The screenshot (PNG, JPEG, HEIC) or video (.mov, .mp4, .m4v, chosen by extension). Required. |
--device, -d |
A device id from bezelbub devices. Leave it out to detect from pixel size. |
--color, -c |
A color name or id, case-insensitive. Defaults to the device's default color. |
--orientation |
portrait, landscape, or auto (the default, taken from the input's shape). |
--background |
A hex color (#RRGGBB or #RRGGBBAA) or transparent. Defaults to transparent for images and black for video. transparent on a video switches the output to HEVC-with-alpha .mov. |
--output-size |
Scale the result, keeping the bezel's aspect: a width (1920), an exact WxH that matches the aspect, or a percentage (50%). Images go from 16 to 16,384 px, videos from 16 to 7,680 px. |
--output, -o |
Where to write the result. Defaults to <input>-framed.png, .mp4, or .mov beside the input. |
--webm |
Also write a VP9/WebM copy with alpha. Video with --background transparent only; needs ffmpeg on PATH. |
--json |
Print a JSON result on stdout instead of a text summary. |
devices lists the whole catalog (ids, display names, colors, orientations, screen sizes, and each display device's known capture sizes), or narrows it to the devices that fit an --input file or a bare --dimensions value. Filtering always exits 0. An empty matches array is the signal that nothing fits, and nearest (by aspect ratio) fills in when that happens.
JSON output
frame --json prints one object:
{
"color" : "Cosmic Orange",
"device" : "iphone17pro",
"height" : 2760,
"kind" : "image",
"orientation" : "portrait",
"output" : "/path/shot-framed.png",
"width" : 1350
}
kind is "image" or "video". For video you also get "transparent": true|false and, when --webm ran, the "webm" output path. devices --json prints an array of {id, displayName, defaultColor, colors, landscapeOnly, hasPortraitBezel, screenWidth, screenHeight, captureSizes}. With --input or --dimensions it prints {width, height, matches, nearest} using the same device objects, and nearest is filled only when matches is empty.
Exit codes
Each failure type has its own code, so a script can branch without parsing stderr:
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | A flag value we couldn't parse, such as a malformed --background or --output-size |
| 2 | Unknown, ambiguous, or undetectable device. stderr lists the candidates. |
| 3 | Unknown color. stderr lists the device's valid colors. |
| 4 | We couldn't read the input image or video |
| 5 | Compositing or video export failed |
| 6 | We couldn't write the output |
| 7 | The --webm conversion failed because ffmpeg is missing from PATH or returned an error |
| 64 | Malformed arguments (the standard EX_USAGE) |
For AI agents
We built the CLI for non-interactive, programmatic use, by LLM agents (Claude Code, MCP tool wrappers, CI bots) as much as by people:
- Nothing prompts. Every input is a flag with a default, so a call either finishes or fails right away.
- Both subcommands take
--jsonand return the shapes shown above. - Errors tell you how to fix them. stderr includes did-you-mean device and color ids, the devices that fit the input's pixel size, and the nearest sizes, so an agent can correct the next call without a human.
- Exit codes 2 through 7 name the failure type (table above), so an agent can branch without reading text.
- Pipes stay clean. We only print video-export progress to stderr when it's a TTY, so captured output stays parseable.
- A typical agent flow: run
bezelbub devices --input shot.png --jsonto check the match, thenbezelbub frame --input shot.png --jsonand readoutputfrom the result.
This repo also includes a ready-made Claude Code skill at skills/bezelbub-cli/ that teaches an agent the whole workflow. To install it for all your projects, copy it into your user skills directory:
cp -R skills/bezelbub-cli ~/.claude/skills/
There is also an MCP server, @dgr_labs/bezelbub-mcp, that wraps the CLI as frame_image, frame_video, and list_devices tools.
Requirements
- macOS 14 or later, iOS 17 or later
- Xcode 16 or later
- XcodeGen
How it's put together
The framing engine lives in BezelbubKit, a Swift package with no UI (BezelbubKit/). It does one transformation, from a screenshot, a device id, and an orientation to a framed image, using Core Graphics only, so it runs fully offscreen with no SwiftUI, no app state, and no GUI session. Video framing lives in a sibling product, BezelbubVideoKit, built on AVFoundation, so still-image consumers like the Share Extension don't pull in the video pipeline. The macOS app, the iOS app, the Share Extension, and the bezelbub CLI are all thin clients of these packages. The bezel and mask assets ship inside BezelbubKit and resolve through Bundle.module.
Building it
We generate the apps with XcodeGen:
xcodegen generate
open Bezelbub.xcodeproj
Schemes:
- Bezelbub builds the macOS app
- Bezelbub-iOS builds the iOS app and the Share Extension
The engine and CLI build with SwiftPM:
cd BezelbubKit
swift build # BezelbubKit library and the bezelbub CLI
swift test # engine round-trip tests
License
Copyright 2026 DGR Labs, LLC. All rights reserved.
Bezelbub MCP questions
How do I add Bezelbub MCP to Claude Code?
Run claude mcp add bezelbub -- npx -y @dgr_labs/bezelbub-mcp in your terminal. Add --scope user to make it available in every project.
How do I add Bezelbub MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Does Bezelbub support transparent video backgrounds?
Yes, you can export framed recordings with a fully transparent background as HEVC-with-alpha in a QuickTime .mov file.
How does the tool detect which device to use?
It detects the device from the input's pixel dimensions, matching exact resolutions for iPhones and iPads or specific capture sizes for Macs and Apple TV.