The MCP server “io.github.Cassette-Editor/oh-my-cassette” provides a chat-driven AI workflow for creating video montages. Its description highlights beat-synced cuts, auto-matched music, subtitle generation, and transitions.
🛠️ Key Features
Beat-synced cuts
Auto-matched music
Subtitles
Transitions
🚀 Use Cases
Creating AI-generated video montages from chat instructions
Producing music-aligned edits with subtitles and transition effects
⚡ Developer Benefits
Integrates chat-based direction with montage editing steps (cuts, music matching, subtitles, transitions)
⚠️ Limitations
Available metadata includes only the server’s name and high-level description; no tool count, topics, or operational constraints were provided.
Oh My Cassette is an open-source AI video editing plugin and local MCP server for Claude Code, Codex, Hermes Agent, and OpenCode. It turns natural-language chat into finished montage videos on Cassette — beat-synced cuts, auto-matched music, subtitles, transitions, and picture-in-picture — with minimal token overhead.
The agent does the parts that make editing tedious: it watches every clip, picks the shots, plans the cut, syncs it to the beat, and renders — while you stay in chat. Because it runs through your agent, you can do all of it from your phone.
💬 Chat-to-Edit
Describe the video in plain language — the agent handles shot selection, pacing, and the timeline, so you never open an editor.
🎵 Smart Music Matching
Finds and syncs music to the mood and rhythm of your footage, so the cut lands on the beat without you marking a single one.
👀 Nothing Renders Until You Say So
Every turn returns a timeline digest and a contact sheet you can review in seconds — you approve the plan before a frame is rendered.
🖥️ How it works
Upload your clips, describe the video you want, and the agent edits it.
Time
What happens
0:00
The brief — the same prompt as the Travel Vlog case below, typed into Claude Code
0:05
14 files upload to Cassette; every clip is analyzed for scene content
0:13
The agent edits on its own — shot selection, titles, picture-in-picture, beat-synced cuts
0:16
The timeline comes back as a readable digest, with a clickable preview link
0:25
One cmd+click opens the real contact sheet — one frame per clip, zero render
0:30
Nothing renders until you say so; the export runs on your go
0:36
The finished cut lands in the project folder
The cut it produced
The screen recording is compressed to keep this page light, so the terminal text looks softer here than it does on your machine; the cut below it is the full-quality render. Prompt to rendered file took about 13 minutes of real time, sped up above. A person's face is pixelated in both the screen recording and the cut it produced, for privacy — that blur is not something the agent added.
Token cost: that session used 45K output tokens and 20.3M billed tokens in total (19.8M of them cache reads) across 4 turns on Claude Opus 4.8 — roughly $13 at API list price, measured from the Claude Code transcript of this exact recording. The editing itself runs on Cassette, so the agent only pays for the brief and the timeline digests, not for the footage.
🎬 Case Videos
Every case below was edited end-to-end by an AI agent through Oh My Cassette, from the exact prompt shown — real inputs, real processing times, and the output is what the agent delivered.
Travel Vlog
🎞️ Input: 13 video clips · 1 audio track ⏱️ Processing Time: 15 mins
Prompt
Edit a 30-second travel vlog using all materials with a clear viewing flow. Add the title subtitle "KOTA KINABALU" at the beginning and end. Include the vlog shooting time, overlay the character video onto similar scenic shots as a picture-in-picture effect, keep the rhythm light and memorable, and use hard cuts plus music beat sync for a fresh vacation feeling.
TravelVlogBeat SyncPiP
Cooking Tutorial
🎞️ Input: 12 video clips · 1 audio track ⏱️ Processing Time: 8 mins
Prompt
Use these materials to edit a cooking video for stir-fried pork with green peppers. Keep the steps smooth, preserve the cooking sounds, and add simple subtitles. The subtitles can be generated based on the visuals to help viewers understand each step. Keep the style clean and natural without covering the ingredients.
FoodTutorialExplainer
Commercial
🎞️ Input: 15 video clips · 15 sound effects · 1 audio track ⏱️ Processing Time: 13 mins
Prompt
Use these materials to edit a 15-second product commercial. Start with opening the bottle cap, add bubbles, water splashes, ice cubes, and product details in the middle, and end with the full product and brand. Keep it refreshing, thirst-quenching, and ad-like.
ProductShortCommercial
→ See all six cases — daily vlog, cinematic short, and game highlights, each with its exact prompt. ★ More cases are on the way. Star the project to follow along.
🏄 Try without installation
Upload a clip, type an edit, watch it happen — from a desktop or mobile browser, with no agent installed locally.
Evaluation demo — unauthenticated and public. Don't upload anything sensitive, private, or copyrighted.
Full demo terms — data handling, third-party processing, and availability
Uploaded files, prompts, generated outputs, job state, and troubleshooting metadata may be processed by this demo server, Cassette, DeepSeek, and third-party music/search providers used by the BGM flow. Treat anything you upload as visible to the demo operator and the external services involved in the workflow.
The demo may be reset, rate-limited, unavailable, or changed at any time. We do not guarantee data retention, deletion timing, confidentiality, fitness for production use, output quality, copyright compliance of generated/editing results, or uninterrupted service. You are responsible for the content you upload and for reviewing any generated output before sharing it.
Browser refreshes, tab closes, or navigation away from the demo start a new web session and best-effort cleanup the previous session's temporary uploads, chat history, and finished job files.
By default the demo uses the server-side DeepSeek configuration when available. You can open Settings in the web UI and provide your own DeepSeek API key for testing. Your key is sent only with requests to this demo server and is not written to this repository or server-side disk by the web app, but it still transits the public demo server; use a key you can rotate and monitor.
Start a new Codex task after installation so plugin discovery runs again. The plugin contributes the host-neutral cassette-video-edit skill and a local MCP process named cassette.
Claude Code
bash
claude plugin marketplace add Cassette-Editor/oh-my-cassette
claude plugin install oh-my-cassette@cassette-editor
Restart Claude Code after installation. You can verify the installation with:
bash
claude plugin details oh-my-cassette@cassette-editor
Claude Code can keep the plugin up to date on its own once you enable auto-update for the marketplace — see Update.
OpenCode
OpenCode's plugin manager installs npm packages only, and its plugins cannot contribute MCP servers, so there is no marketplace entry to add. One command instead:
That downloads the current release, writes the cassette server into ~/.config/opencode/opencode.json (merging with any servers and settings already there), and installs the host-neutral cassette-video-edit skill into ~/.config/opencode/skills/. Restart OpenCode afterwards.
Re-run the same command to update. Only git is not required — the release tarball is fetched with Python's standard library.
Credentials are shared with the Codex and Claude installs, so if you have already set those up there is nothing more to do. Otherwise the installer prints the setup_local_mcp.py command to finish authentication.
The plugin tree lands in ~/.oh-my-cassette (override with OMC_HOME). --dry-run previews the changes. If you prefer a git checkout, clone it and run the installer from there — it registers that tree and leaves it alone, and --sync fast-forwards it to the release channel.
Any other MCP host
The runtime is host-neutral, so any client that launches a local stdio MCP server can use it. Point the client at scripts/run_local_mcp.py (run with python3, or python on Windows) and set CASSETTE_RUNTIME_ADAPTER=mcp. The server ships full workflow guidance in its MCP instructions, and every tool returns a typed phase/next_action so a host without the packaged skill can still drive the flow. For the best experience, also install the cassette-video-edit skill (or equivalent system prompt) so the guided-choice and review steps are followed.
Hermes
Install through the Hermes plugin manager (recommended):
The Hermes installer prompts for your Cassette account email and password and saves them to ~/.hermes/.env. Then run the setup finisher — it installs Playwright Chromium into the Hermes Python environment, detects ffmpeg/ffprobe, and lets you pick the Cassette region — and enable the plugin:
Codex and Claude use the same self-contained runtime. In this README, MCP server means a local child process connected over stdin/stdout: it opens no port and does not depend on the FastAPI web-demo service. The separate Cassette backend remains the editing engine and continues to handle authentication, media processing, agent runs, project state, and rendering.
The web demo is intentionally different. Browsers still need the retained FastAPI server for uploads, chat sessions, and frontend endpoints; none of that behavior is removed by the local MCP plugin.
First-run authentication
Missing credentials do not prevent the MCP process from starting. The first tool that needs Cassette returns auth_required and an exact private-terminal setup command. Run that command outside the agent conversation; it prompts for the password with getpass, verifies the account before writing anything, and stores credentials in the platform-standard Oh My Cassette config directory.
Credentials may also come from process environment variables. Environment values take precedence over protected local config. Importing an existing Hermes .env is explicit and optional:
The setup command creates config directories with mode 0700 and credential files with mode 0600, rejects symlinks and permissive files, and never persists access or refresh tokens. If the account does not have full API access, setup reports the optional browser path instead of silently changing transports.
Resetting the password
If the stored password stops working, auth_required and auth_failed both carry the command that resets it:
This replaces the account password everywhere, including other machines, and saves the new one to credentials.json:
macOS: ~/Library/Application Support/Oh My Cassette/credentials.json
Linux: ~/.config/oh-my-cassette/credentials.json (or under XDG_CONFIG_HOME when set)
Windows: %APPDATA%\Oh My Cassette\credentials.json
Usage: point it at your clips
Start your agent in the folder that holds the clips — or in any parent of it. That folder is the trusted media root (CASSETTE_PROJECT_ROOT, set to the host's project directory), and everything beneath it is ingestible, so ~/videos/trip/raw/*.mp4 works when you start in ~/videos/trip. Clips somewhere else? Register that directory once:
Ingesting a file outside every trusted root fails with source_path_not_allowed.
Say what you want, in one message, naming the folder. No upload step to run yourself — the agent ingests the files it needs.
Edit the clips in ./footage into a 30-second travel vlog with beat-synced cuts. Add the title "KOTA KINABALU" at the start and end, and keep the rhythm light.
Keep going in the same conversation. Each turn commits the edit and returns a timeline digest, a contact sheet, and a live editor link — nothing renders. "Make the intro shorter", "swap the music for something calmer", "undo that" all continue the same session, and the agent remembers.
Say "export" when you're happy. That's the only thing that starts a render; the finished file lands in cassette/exports/<job_id>/.
Supported inputs are video, image, and audio files (.mp4, .mov, .jpg, .png, .mp3, .wav, and friends). Mixed folders are fine — send the footage and the music track together.
Guided editing flow
What the plugin does under the hood on each of those turns:
Ask Codex or Claude to edit one or more media files in the current project.
The plugin ingests only media inside the active project or another explicitly trusted root. It canonicalizes paths and rejects traversal and symlink escapes.
Describe the edit, answer any guided choices, and start the job. MCP jobs run in the background by default.
The host checks status with bounded 30-second long polls. During a long poll the runtime emits MCP progress notifications (visible in hosts that request them), so the wait shows live stage updates instead of a silent block. The skill monitors for up to 25 minutes, then returns the still-running job ID so you can continue later without tight-polling.
If Cassette needs a real user decision, answer it with the returned job ID. On hosts that support MCP elicitation, cassette_job_status collects the answer inline and returns the already-resumed status; other hosts use the cassette_answer_question round-trip. API jobs persist their private continuation metadata across host restarts.
When editing completes, review the result. Rendering starts only after an explicit export decision.
The result contains validated absolute paths, file URIs, MIME type, size, and an MCP resource link for each exported artifact. Large media bytes are never embedded in the tool response.
When a background job reaches a terminal state (finished, needs input, failed, or cancelled), the MCP runtime posts a best-effort local desktop notification — osascript on macOS, notify-send on Linux — so you learn a long render is done even after the monitor budget hands the job back. Set CASSETTE_MCP_NOTIFY=0 to disable it.
Sessions are isolated by a cryptographically random session ID. Codex and Claude share host-neutral storage, so you can deliberately hand a session or job ID from one host to the other; nothing is shared implicitly.
Additional trusted media directories can be registered during setup:
Exports stay under the shared Oh My Cassette data directory at cassette/exports/<job_id>/. Only files contained in that job-specific directory can be returned.
API and optional browser transports
The API transport is the default. It connects directly to the separate Cassette backend, retries authentication once after a 401, and keeps access tokens in memory only. Because API continuation metadata is persisted, paused API jobs can resume after Codex or Claude restarts.
Browser transport is an explicit fallback for accounts without full API access and for parity diagnostics. Install pinned Playwright and Chromium only when needed:
bash
python3 scripts/setup_local_mcp.py --with-browser
Browser jobs can resume while the same MCP process is alive. After a host restart they return browser_session_lost, because live browser objects cannot be persisted.
MCP tools
The local MCP runtime exposes the same 14 tool names as Hermes:
Tool
Purpose
cassette_ingest_media
Safely ingest trusted project media into an isolated session
cassette_list_assets
Read the session's media manifest
cassette_make_prompt
(legacy, browser transport) Build a full edit brief
cassette_match_bgm
Match Free To Use background music
cassette_match_exact_bgm
Match a specific title and artist
jamendo_music_matcher
Match structured Jamendo preferences
cassette_answer_question
Answer a guided question or resume a paused job
cassette_run_job
Run one conversational turn (message = the user's verbatim words); export=true renders
cassette_job_status
Read status or wait briefly for a change
cassette_review_completion
Review completion and explicitly approve export
cassette_cancel_job
Request cooperative cancellation
cassette_timeline
Read the live project timeline as a bounded text digest (+ optional contact sheet)
cassette_edit
Surgical no-LLM edit / undo through the manual command lane (CASSETTE_DIRECT_EDIT=1)
cassette_config
Get/set the session's model + thinking level (static product list, applies next turn)
Every tool returns a structured envelope with ok, typed data or error, session_id, job_id, the current phase, and a runtime-derived next_action.
The live editor deep link and plan review
Every session on the API transport carries ONE stable editor_url — a …/try?projectSessionId=<id>&chatSessionId=<uuid> link that opens the real Cassette editor on the session's live conversation: the timeline repaints as edits land, the preview plays without any server render, and the plan-review card is interactive. The link stays the same across every turn of the session (jobs are conversational turns on one persistent agent thread with memory). Anyone with the link can view and edit that one project (the same capability-URL posture as Cassette's public try page), so treat it like a share link.
Two concurrency semantics worth knowing: a plugin turn never cancels a run started from the open editor tab (it fails typed as thread_busy instead — wait and retry), while typing a fresh message in the tab DOES cancel an in-flight plugin turn (the tab takes over; existing product behavior).
Behavior change (0.4.1): the agent now receives the user's message verbatim (no brief wrapper), sessions are multi-turn on one thread, and a turn ends with the edit committed but nothing rendered — the envelope carries timeline_delta, quality.timeline_ctl, and a contact-sheet preview instead; pass export=true on the turn where the user asks to finish (browser transport keeps its render-per-job behavior). Model/thinking are session preferences via cassette_config — never asked upfront, defaults match the web editor.
Behavior change (0.4.0): on MCP hosts, edit_plan_review now surfaces as a real question by default (CASSETTE_PLAN_REVIEW=user) instead of being silently auto-approved — answer with approve, revise <feedback>, or reject, in chat or in the open editor tab (first answer wins). Set CASSETTE_UNATTENDED=1 to restore the previous fully headless behavior. Status envelopes additionally carry timeline_delta (what changed) and plan_progress, fed by the run's SSE event stream (CASSETTE_API_STREAM=0 disables).
Ready to Use with Hermes 📼
Now you can pick up your phone and DM your agent! Don't forget to keep your agent alive and network connected.
In QQ or Telegram:
Send one or more video, image, or audio files.
Wait for the saved-material acknowledgement.
Send an edit instruction in the same conversation, or prefix it with /edit. Your words go to the Cassette agent verbatim — no model/optimization/BGM questionnaire. Use /refine, /music, or /cassette_model when you want those.
Each turn ends with the edit saved (timeline delta + contact-sheet preview + live link, no render). Keep editing in the same conversation — the agent remembers. Say "export" when you want the video, and the plugin renders and delivers it through the gateway when supported.
Command
Explanation
/new or /reset
Clear your assets and start a new conversation with Hermes
/edit <instruction>
Edit the current video based on your instruction.
/refine <instruction>
Refine your edit instruction and start editing.
/music <BGM request>
Match and add a BGM to your assets based on your request.
/cut
Stop the current Cassette edit.
/check_assets
Check the uploaded assets and their status.
/cassette_model
Select the current Cassette model and thinking level.
/cassette language zh
Set Cassette’s response language to Chinese.
/cassette language en
Set Cassette’s response language to English.
/cassette status <job_id>
Check the status of a specific job.
/cassette cancel <job_id>
Cancel a specific job.
Assets and video state are preserved within the same conversation session. You can send additional messages in the same session to further modify the edited video results.
Use /new or /reset to start a fresh Hermes session and clear the live Cassette browser session and your assets for that conversation.
QQ is set to Chinese and Telegram is set to English by default, you can set language by command /cassette language zh/en manually.
Update
The runtime checks the release channel once a day and, when a newer version exists, tells your agent — which mentions it once and offers to run the command below for you. Set CASSETTE_UPDATE_CHECK=0 to turn that check off.
Host
Automatic
Manual
Claude Code
yes, once enabled (below)
claude plugin marketplace update cassette-editor && claude plugin update oh-my-cassette@cassette-editor
Claude Code can update marketplaces and their plugins in the background shortly after a session starts, then prompts you to run /reload-plugins. It is off by default for third-party marketplaces, so turn it on once — scripts/setup_local_mcp.py offers to do this during setup (skip with --no-auto-update), or do it yourself in /plugin → Marketplaces → cassette-editor → Enable auto-update, or in ~/.claude/settings.json:
Declaring it in settings.json wins over the /plugin toggle — Claude Code syncs the declared value into its marketplace state and then points you back at the settings file to change it.
Claude Code's DISABLE_AUTOUPDATER turns off all automatic updates including plugins; pair it with FORCE_AUTOUPDATE_PLUGINS=1 to keep plugin updates while managing Claude Code itself manually.
Codex
Codex refreshes configured git marketplace snapshots on its own, but installed plugins are cached per version, so one command applies the new one:
bash
codex plugin marketplace upgrade cassette-editor # only needed if the snapshot is stale
codex plugin add oh-my-cassette@cassette-editor
OpenCode
Re-run the install command — it is the same command for installs and updates:
The local launcher updates its locked, plugin-managed virtual environment automatically on the next start after any of these. Browser binaries are installed only when requested.
See CHANGELOG.md for what changed in each release.
Migrating a symlink install to the Hermes plugin manager (optional)
Existing symlink installs keep working — migration is optional. To switch:
bash
rm ~/.hermes/plugins/cassette # removes only the symlink, not your checkout
hermes plugins install Cassette-Editor/oh-my-cassette
hermes gateway restart
Your credentials in ~/.hermes/.env and the plugin's enabled state carry over;
already-set values are not prompted again. Don't run
hermes plugins install --force on top of a symlink — it fails with a
confusing error instead of replacing it.
❓ FAQ
Which AI agents does Oh My Cassette work with?
Claude Code, Codex, OpenCode, and Hermes Agent are supported out of the box, and any other MCP host can connect to the local cassette MCP server. Sessions live in a host-agnostic data directory, so you can start an edit in one host and continue it in another.
Does it edit videos locally or in the cloud?
The plugin runs locally beside your agent and handles media ingestion, edit planning, and job supervision. The actual editing and rendering happen on Cassette, so you don't need a GPU or any editing software installed.
Do I need a Cassette account?
Yes. The installer asks for your Cassette account email and password on first run and stores them locally; the plugin authenticates with Cassette on your behalf.
What kinds of videos can it make?
Montage and story edits — vlogs, travel videos, music-driven shorts, cooking tutorials, product commercials, and game highlights — with beat-synced cuts, subtitles, picture-in-picture, transitions, and auto-matched background music. See Case Videos for real examples with prompts and processing times.
Can I see what the agent is doing mid-edit?
Yes. After each editing turn you get a timeline contact sheet, a per-turn preview, and a live editor deep link into the Cassette timeline; before the edit runs, the agent surfaces the plan as a storyboard sheet (one source frame per planned beat) for review.
Can I try it without installing anything?
Yes — the public web demo runs the full workflow in your browser. It is unauthenticated and for evaluation only, so don't upload sensitive content.
Is Oh My Cassette free and open source?
This plugin is free and open source under the MIT license — all of it, including the MCP server, the skill, and the web demo.
Rendering runs on Cassette, a separate hosted service that requires an account. See Cassette's pricing for what an account costs. You can try the whole workflow with no account at all through the web demo.
🔨 Development & Troubleshooting
Setup for contributors, the full configuration reference, transport internals, the diagnostic
scripts, and answers to common runtime problems all live in
docs/development.md.
Quick diagnostic — run this first when something misbehaves:
