keyframe-mcp

keyframe-mcp

Create, inspect and export 2D skeletal animations in Keyframe.it 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.

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.

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.