keyframe-mcp

keyframe-mcp

Create, inspect and export 2D skeletal animations in Keyframe.it, and rig, animate, play-test and export pixel-art sprites in Sprite Puppeteer, from any MCP client.

Install

Requires Node 18+ and Google Chrome. No browser download or Keyframe account is needed.

claude mcp add keyframe -- npx -y keyframe-mcp

Other clients:

{"mcpServers":{"keyframe":{"command":"npx","args":["-y","keyframe-mcp"]}}}

Version 0.2.0 adds persistent projects, named tools with validated schemas, complete clip creation, animation checks, editable image layers and file exports. Restart the MCP client after updating. For a local checkout, run npm ci in mcp/, then configure node with the absolute path to mcp/server.mjs.

Version 0.2.1 adds ownership metadata for the official MCP Registry, where the server is listed as io.github.kendall8388/keyframe.

Version 0.3.0 adds 18 puppeteer_* tools for Sprite Puppeteer: sample and your own characters, camera sets and directions, contact sheets, keyframed moves, and sheet, Godot, Unity, GameMaker, PNG-frame, Spine, GIF and project exports.

Workflow

• keyframe_open resumes a dedicated Chrome profile and waits for saved projects to restore.
• Read keyframe_methods, keyframe_call {method:"recipes"} and the current document with keyframe_call {method:"getState"}.
• Build a complete clip with keyframe_build_animation. All poses are validated before the document changes. Partial transform values carry forward from setup. loop:true copies the first pose to the end; replace:true replaces all tracks in an existing clip. FPS applies to the entire project.
• Review keyframe_contact_sheet and keyframe_check_animation. Inspect motion with keyframe_call {method:"renderClip",args:["idle"]}. Warnings can be intentional; contact-sheet framing is fitted to the clip, and loop transform checks exclude springs.
• keyframe_export {format:"project"} writes an editable JSON file. Use gif for a preview or spine for a ZIP with skeleton, atlas, textures and test.html. Files return as MCP resource links plus local paths; supporting clients can read them with resources/read.
• keyframe_open_result saves and opens visible Chrome so the user can continue editing. The window lasts while the connector is running; saved projects persist after shutdown.

Example clip tool arguments (use real bone names from the project):

{"spec":{"name":"idle","duration":2,"fps":24,"loop":true,"poses":[{"time":0,"bones":{"root":{"y":0,"scaleY":1}}},{"time":1,"bones":{"root":{"y":-6,"scaleY":1.03}}}]}}

Read keyframe_session and pass its projectId and revision in expected to build/configure/layer edits to reject stale commands. Requests run sequentially. Changes are saved before the tool responds. If saving fails after a mutation, the error says applied:true; retry keyframe_save before closing.

Tools

Tool	Purpose
keyframe_open	Open/resume the editor, optional URL
keyframe_methods	Discover all scripting methods
keyframe_call	Call a method with positional JSON arguments; image results appear inline
keyframe_session	Active project and revision
keyframe_list_projects / keyframe_open_project	Find and reopen saved projects
keyframe_save	Wait for browser storage to commit
keyframe_build_animation	Create a complete validated clip in one undo step
keyframe_configure_animation	Duration and project FPS
keyframe_apply_pose	Batch named bone transforms in the active clip
keyframe_contact_sheet	Timestamped pose grid, empty/edge-frame checks
keyframe_check_animation	Loop, visibility and rig diagnostics
keyframe_image_layers / keyframe_image_layer_png	Inspect editable layers and pixels
keyframe_edit_image_layers	Atomic layer add/update/reorder/delete, including editable text
keyframe_export	Project JSON, GIF or Spine ZIP as files
keyframe_open_result	Save and show the editable result
keyframe_screenshot	Whole editor UI

Every named tool advertises its JSON Schema. Errors use MCP isError:true and {ok:false,error}. The generic call tool remains available for rigging, slicing, meshes, physics and other advanced methods.

Sprite Puppeteer

Sprite Puppeteer rigs and animates pixel-art sprites and lets you play-test them in an arena. It opens as a second page in the same connector profile. There are two kinds of character: rigged (one image with a skeleton, built-in moves plus moves you create) and sprite-sheet (every frame already drawn, in camera sets such as side, isometric and top-down, with up to eight directions).

• puppeteer_open (optionally {sample:"orc"} or {sample:"golem"}), or puppeteer_load_image {path:"/abs/path/hero.png"} for your own art (PNG, GIF, WebP, JPEG, Aseprite or PSD; the skeleton auto-fits).
• puppeteer_state lists moves, camera sets and directions (or views), and settings.
• Judge motion with puppeteer_contact_sheet {move:"walk"}; pick angles with puppeteer_set_view {set:"iso8", dir:"S"}.
• Rigged characters: read puppeteer_move_guide, then puppeteer_create_move with keys that list only the channels that change. Check it with a contact sheet and refine with replace.
• puppeteer_export {format:"godot", moves:"all", dirs:"8"} (or sheet, unity, gm, frames, spine, gif, project) writes the file and returns a resource link and local path.
• puppeteer_open_result shows the page in visible Chrome.

Example move for the sample golem (puppeteer_open {sample:"golem"} first):

{"spec":{"name":"Overhead slam","dur":1.1,"loop":false,"keys":[{"t":0,"pose":{}},{"t":0.35,"ease":"out","pose":{"y":18,"torso":-12,"uarmR":150,"uarmL":150}},{"t":0.55,"ease":"snap","pose":{"y":6,"torso":30,"uarmR":-40,"uarmL":-40}},{"t":1.1,"pose":{}}],"events":[{"t":0.55,"type":"slam"}]}}

Tool	Purpose
puppeteer_open	Open Sprite Puppeteer, optionally with a sample
puppeteer_methods / puppeteer_call	Every scripting method, and a generic call
puppeteer_state	Character, moves, camera or views, settings
puppeteer_play_move	Show a move on the stage
puppeteer_set_view	Camera set and direction (sheets), view (rigged), facing
puppeteer_settings	Background, fps, pixel scale, speed, effects, export options
puppeteer_move_guide / puppeteer_create_move	Pose channels and conventions; add or replace a keyframed move
puppeteer_contact_sheet / puppeteer_render_frame	Frames as images
puppeteer_load_image	Your sprite from disk as a new rigged character
puppeteer_export	Sheet, Godot, Unity, GameMaker, PNG frames, Spine, GIF or project file
puppeteer_list_projects / puppeteer_open_project / puppeteer_save	Projects in the connector profile
puppeteer_screenshot / puppeteer_open_result	The page, and handoff to visible Chrome

The page's API is window.spritePuppeteer; any browser automation can call it directly. See llms.txt.

Storage and handoff

The connector uses its own Chrome profile, not existing personal Chrome tabs. Projects belong to that profile and site origin. Export project JSON and import it in your usual browser to transfer work. Existing projects from version 0.1.0's temporary browser profile cannot be recovered unless previously exported.

Variable	Default	Purpose
KEYFRAME_URL	https://www.keyframe.it.com/	Editor URL; HTTP allowed for localhost development
KEYFRAME_PROFILE_DIR	~/.keyframe-mcp/profile	Persistent browser storage; use separate directories for concurrent instances
KEYFRAME_HEADLESS	1	Set 0 to watch work; open_result switches to visible Chrome
KEYFRAME_EXPORT_DIR	~/.keyframe-mcp/exports	Downloaded artifacts; files remain after shutdown

Close or Apply the human image editor before agent layer edits. Layers retain text, visibility, opacity, blend modes and locks. The composite stays compatible with existing rig/export tools. See the full API reference for operation examples and limits.

Development

npm test runs schema, protocol, persistence, serialization, error and file-resource tests with a fake browser. ../e2e/agent-workflow.html exercises the real editor API, canvas renders, layer compositing, exports and save/reload through a Vite dev server.

MIT — see LICENSE. This license covers the connector; the editor is a separate hosted application.