Reference
FrameJam MCP tools
FrameJam exposes 12 tools over stdio and streamable HTTP. Your agent normally calls them in this order: open_picker, wait_for_pick, open_review, wait_for_feedback, add_version, then wait_for_feedback again. Install the plugin first, then use playbooks and styles through list_playbooks / get_playbook and list_presets / get_preset. Feedback lands on the review page.
Playbooks
open_picker
At the start of a new video, or when you type /framejam:playbook or /framejam:style.
Opens a pick page in FrameJam where you choose a playbook and/or a style for this video, or none. Returns the page's URL, which the agent opens and posts in chat.
| Argument | Type | Description |
|---|---|---|
kinds | ("playbook" | "style")[] | What to pick. Default: both. |
title | string | What the video is about, shown on the page. |
Returns { pickId, url, kinds, next }
wait_for_pick
Right after open_picker.
Waits until you press Start on the pick page, then returns the playbook (as get_playbook) and the style (as get_preset), or null for none. Returns pending after about 50 seconds so the agent calls it again.
| Argument | Type | Description |
|---|---|---|
pickIdrequired | string | From open_picker. |
timeoutSeconds | number | Max seconds to wait before returning pending (default 50). |
Returns { status: "picked", playbookId, styleId, playbook, style, next } or { status: "pending" | "cancelled" }
list_playbooks
The agent looks for a playbook that fits your request.
Lists the built-in playbooks and your own from ~/.framejam/playbooks, with what you bring, what you get, the cost and the creator.
| Argument | Type | Description |
|---|---|---|
query | string | Free-text search over names, taglines, descriptions, what you bring and tags. |
Returns { count, playbooks: [{ id, name, tagline, bring, get, format, cost, project, creator, galleryUrl }] }
get_playbook
You name a playbook, for example from a copied prompt.
Returns one playbook: its playbook.json, the full SKILL.md method, its local folder and files, how a style combines with it, and the styles made for it (with their ready settings when styleId is one of them).
| Argument | Type | Description |
|---|---|---|
idrequired | string | Playbook id, for example clean-cut. |
styleId | string | The style picked for this video, so stylesSentence names it. |
Returns { playbook, skill, playbookDir, files, project, stylesSentence, galleryUrl, next }
Styles
list_presets
The agent looks for a style that fits, or you ask it to choose one.
Lists the built-in styles and your own from ~/.framejam/presets, optionally filtered. Each entry carries a gallery URL.
| Argument | Type | Description |
|---|---|---|
mood | string | Filter by mood, for example bold or calm. |
pacing | "slow" | "medium" | "fast" | Filter by pacing. |
format | "16:9" | "9:16" | "1:1" | Filter by aspect ratio. |
query | string | Free-text search over names, taglines, descriptions, moods and tags. |
Returns { count, presets: [{ id, name, tagline, mood, pacing, format, durationSeconds, galleryUrl }] }
get_preset
After choosing a style.
Returns the look: the full style.json (palette, fonts, easing, transitions, text animations, rhythm), the guide of look rules, and what the example video shows. The agent builds your subject in that look and doesn't copy the example's scene. The example composition is listed, not pasted; the agent opens it only to see how a technique is built.
| Argument | Type | Description |
|---|---|---|
idrequired | string | Preset id, for example neon-terminal. |
includeTemplate | boolean | Also return the example composition's source files (up to 200 KB). |
Returns { style, guide, example, howToUse, presetDir, templateDir, templateFiles, templateSource?, previewVideo, galleryUrl }
Reviews
open_review
After the first render, or once the storyboard panels exist.
Creates a review and returns its URL for you to open. Called again for the same project (same title, or same panelsDir for a storyboard), it adds the next version instead of a new review. Pass panels or panelsDir instead of a video to review a storyboard.
| Argument | Type | Description |
|---|---|---|
title | string | Name shown in the review list. |
videoPath | string | Absolute path to the rendered mp4 or webm. It is copied, so later renders can overwrite the file. |
panels | array | Storyboard panels in order: image paths, or { path, title, caption } objects. Relative paths are read from panelsDir. |
panelsDir | string | Folder of storyboard images (png, jpg, webp, gif, svg), sorted by file name. |
transcriptPath | string | Videos with speech: a transcript of this render (.srt, .vtt, or word-timings JSON from Whisper, whisper.cpp, Deepgram or ElevenLabs). You read along under the timeline and can comment on words. Without one, FrameJam transcribes the render on your computer if whisper.cpp is installed. |
reviewId | string | Add to this existing review instead of matching by project. |
note | string | One line about this version, shown to you as a toast. |
Returns { reviewId, url, version, created, next }
wait_for_feedback
Right after sharing the review URL, and after every new version.
Blocks until you press Finish review, then returns your comments as JSON, as a markdown prompt and as up to six inline frames. After about 50 seconds with nothing it returns status: pending and the agent calls it again, up to 12 times in a row (about 10 minutes), then stops and tells you to say 'apply my FrameJam feedback'. It sends MCP progress notifications every 10 seconds while it waits.
| Argument | Type | Description |
|---|---|---|
reviewIdrequired | string | The review to wait on. |
timeoutSeconds | number | How long to block before returning pending. Default 50, maximum 300. |
Returns { status: "feedback", revised?, reviewId, title, url, currentVersion, videoPath, panelsDir, panels, message, comments[], next } or { status: "pending", reviewId, url, next }
get_feedback
You say "apply my FrameJam feedback" and the agent wasn't waiting.
Returns the newest round of comments right away. Without a reviewId it picks the review whose comments haven't reached the agent yet. If you wrote comments but never pressed Finish review, they are finished now and the version is locked, exactly as if you had pressed it.
| Argument | Type | Description |
|---|---|---|
reviewId | string | Optional. Picks the most relevant review when omitted. |
include | "latest" | "all" | Return only the newest round (default), or every version's comments. |
Returns { status: "feedback" | "already_delivered" | "empty", versions[], comments[], next, … } with the same fields as wait_for_feedback
add_version
After applying your comments and re-rendering.
Attaches the new render (or new storyboard panels) as the next round. It opens with an empty comment list, and the note is shown to you as a toast.
| Argument | Type | Description |
|---|---|---|
reviewIdrequired | string | The review to add to. |
videoPath | string | Absolute path to the new mp4. Use a new file per version so earlier versions stay comparable. |
panels | array | New storyboard panels. |
panelsDir | string | Folder of storyboard images. With no media at all, the previous panelsDir is read again. |
transcriptPath | string | A transcript of the new render, when the timing of the speech changed. |
note | string | One line about what changed. |
Returns { reviewId, version, url, next }
list_reviews
The agent needs to find a review.
Lists video and storyboard reviews, newest first, with their URL and where each round stands: awaiting_user, user_commenting, sent_not_delivered or delivered_to_agent.
No arguments.
Returns { count, reviews: [{ reviewId, title, url, updatedAt, latestVersion, kind: "video" | "storyboard", state }] }
resolve_comments
Optional bookkeeping.
Marks comments as handled. The review page doesn't depend on it: each version is one round.
| Argument | Type | Description |
|---|---|---|
reviewIdrequired | string | The review. |
idsrequired | string[] | Comment ids from the feedback, or ["all"] for every finished comment. |
note | string | What was done. |
Returns { resolved, missing, stillOpen }
The feedback your agent receives
wait_for_feedback and get_feedback return three kinds of content: JSON like the example below, the same comments as a markdown prompt, and up to six inline JPEG frames.
{
"status": "feedback",
"reviewId": "rev_14dea90011",
"title": "Launch teaser",
"url": "http://localhost:2400/review/rev_14dea90011",
"currentVersion": 1,
"videoPath": "/Users/you/videos/launch-teaser/renders/v1.mp4",
"comments": [
{
"id": "c_01",
"version": 1,
"at": "0:01.5",
"time": 1.5,
"position": { "x": 0.42, "y": 0.61, "description": "center of frame (42% from left, 61% from top)" },
"text": "The red line clips the descenders. Give the mask more room.",
"thumbnailPath": "~/.framejam/reviews/rev_14dea90011/thumbs/c_01.jpg"
},
{
"id": "c_02",
"version": 1,
"at": "0:03.1 – 0:05.2",
"time": 3.08,
"endTime": 5.24,
"spoken": "three things you need before launch",
"text": "The three columns land too fast. Hold each one 0.4s longer."
}
],
"next": "Apply every comment to the video, re-render, call add_version with the new render and a note, then wait_for_feedback again."
}atis human-readable;timeandendTimeare seconds.positionis the pin spot as a fraction of the frame, from the top left.thumbnailPathis the frame the comment is on. For a pinned comment the pin is drawn on it, so the agent sees what you pointed at.- With a transcript,
spokenquotes the words in a range comment andspokenAroundthe words near a moment (long quotes are shortened with “…”). They come from the transcript, so names can be misheard. - On a storyboard, comments carry
panel(number, title, caption and image path) instead of a time. revised: truemeans you reopened the round after your agent got it. The new list replaces the old one.thumbnailPathpoints to the frame at that moment, grabbed with ffmpeg.
How the blocking wait works
An MCP tool call is a request the agent is waiting on, so FrameJam simply doesn't answer until there is something to say. It polls the review every 400 ms. After about 50 seconds with nothing it returns { status: "pending" }, which keeps it under client tool-call timeouts, and the agent calls it again without asking you. After 12 pending results in a row (about 10 minutes) the agent stops and tells you to press Finish review and say "apply my FrameJam feedback"; your comments are saved. If the client asked for progress, it sends a notification every 10 seconds.
How to edit videos with Claude, How to make videos with Claude walks through it step by step, with a video. More in Guides.