motion-mcp-server

An MCP server for reading and editing Apple Motion (.motn / .moti) template files.

Scope — read this first

This server edits static template XML on disk. It does not, and cannot, drive a live Motion.app session.

Final Cut Pro exposes a rich AppleScript/Apple Events dictionary, which is what makes a "live control" MCP server (see fcp-mcp-server, the project that inspired this one's architecture) possible for FCP. Apple Motion's own scriptability is limited to three verbs: activate, open, quit. There is no dictionary for pushing parameter values, scrubbing the playhead, or reading back rendered frames from a running Motion document.

So this server's actual capability is: parse a .motn/.moti file (both are the same ozml XML format Motion.app itself writes), let you inspect and mutate its layer/parameter/keyframe/publish-settings tree, and save the result to a new file. Getting the result on screen means opening the written file in Motion.app yourself — motion_open_in_motion does that handoff — or handing a published/rendered template to Final Cut Pro, which does have the rich Apple Events surface (see the sibling fcpxml/commandpost MCP servers for that half of a pipeline).

Related MCP server: fcp-mcp

What it can do

Four tool groups, 16 tools:

• inspect — motion_open, motion_list_layers, motion_list_text_layers, motion_get_parameter, motion_list_keyframes, motion_list_rig

• animate — motion_set_text, motion_set_parameter_value, motion_set_color, motion_create_keyframe_curve, motion_add_keyframe

• rig — motion_publish_parameter, motion_unpublish_parameter (Final Cut Pro's Inspector reads these published/rig parameters when the template is used as an FCP title/generator/effect)

• deliver — motion_save_as, motion_open_in_motion, motion_validate

Authoring motion from scratch

motion_create_keyframe_curve seeds a brand-new <curve> on a leaf parameter that has never been keyframed in Motion — actual dynamic/ procedural animation authoring, not just editing curves Motion already created. This was initially considered too risky to guess at (a curve's type attribute is data-type-specific, and guessing wrong produces a file Motion can't open), so it's grounded in a structural scan of ~4,700 real Motion documents on the machine this was built on: every keyframed leaf parameter observed — Position X/Y/Z, Scale, Angle/Rotation, Opacity, RGB(A) color channels, behavior Amount parameters — used the same universal scalar curve (type="1"), because Motion animates a compound property (Position, Color, ...) by keyframing each numeric child parameter independently rather than through one multi-component curve. A second curve type ("0") does exist on some non-numeric/enum-like parameters (Random Seed, Blend Mode, Interpolation) but never carried an actual keypoint in that scan, so this tool deliberately doesn't attempt to synthesize it — there's no real-file evidence for what a keyed type="0" curve should look like. Verified against both the synthetic fixture and an ephemeral, never-committed round-trip against a real local .motn file.

Once a parameter has a curve — whether Motion created it or motion_create_keyframe_curve did — motion_add_keyframe appends further keypoints to it, in time order.

The ozml schema

Ground truth for the tag shapes this server relies on was read directly from real Motion.app output on the machine this was built on (Motion Projects/Autosave Vault/*.motn, Motion Templates.localized/*.moti), not assumed. See the module docstring in motion/parser.py for the annotated shape, including two nesting traps that are easy to get wrong by guessing:

• Top-level layers are direct children of <scene>, not <timeline> (<timeline> in this schema is only a UI display-state block).

• Text face/outline/glow color and font live under a <style> element that's a sibling of a scenenode's <parameter> tree, not nested inside it.

No personal .motn/.moti file is committed to this repository. The test suite runs against fixtures/sample.motn, a small hand-written synthetic document that reproduces the same tag shapes.

Install

python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"

Run the tests

.venv/bin/python3 -m pytest tests/ -v

Use it from Claude

Add to your MCP client config (Claude Code's .mcp.json, or the Claude desktop app's claude_desktop_config.json):

{
  "mcpServers": {
    "motion": {
      "command": "/absolute/path/to/motion-mcp-server/.venv/bin/python3",
      "args": ["/absolute/path/to/motion-mcp-server/server.py"]
    }
  }
}

Typical workflow: motion_open a template → inspect with the inspect tools → mutate with animate/rig tools → motion_save_as a new file (never overwrites the source implicitly) → motion_validate to confirm the write round-trips → motion_open_in_motion for visual QC.

License

MIT — see LICENSE. Architecture informed by DareDev256's MIT-licensed fcp-mcp-server; this is an independent implementation for a different file format, not a fork.