Connect AI agents with MCP
Lumetrope ships an MCP server so agents such as Claude Code, Codex, Cursor and Claude Desktop can read and edit the animation you have open. It exposes 112 tools and needs Node.js 20 or newer.
How do I set it up?
- Install the Lumetrope desktop app. It copies the MCP server to a fixed path on every launch.
- In the app, click the MCP badge. It shows the exact commands for your OS, with the real server path.
- Enable Local MCP.
- Register the server with your agent (below). Replace
<server path>with the path for your OS.
Where is the installed server?
| OS | Server path |
|---|---|
| macOS | ~/Library/Application Support/com.waygosquad.lumetrope/mcp/lumetrope-mcp.mjs |
| Windows | %APPDATA%\com.waygosquad.lumetrope\mcp\lumetrope-mcp.mjs |
| Linux | ~/.local/share/com.waygosquad.lumetrope/mcp/lumetrope-mcp.mjs |
Claude Code
claude mcp add --scope user lumetrope -- node "<server path>"
Codex CLI
codex mcp add lumetrope -- node "<server path>"
Or edit ~/.codex/config.toml (Windows: %USERPROFILE%\.codex\config.toml):
[mcp_servers.lumetrope]
command = "node"
args = ["<server path>"]
Cursor and Claude Desktop (JSON config)
{"mcpServers":{"lumetrope":{"command":"node","args":["<server path>"]}}}
- Cursor:
~/.cursor/mcp.json - Claude Desktop, macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Claude Desktop, Windows:
%APPDATA%\Claude\claude_desktop_config.json
What can I ask the agent?
- "Read the scene and describe the layers."
- "Add a bouncing ball and give it a hover state machine."
- "Recolour the brand colours to teal, then show me frame 30."
- "Save a version called 'before easing', then ease all position keyframes."
The agent can render frames to images, so it can check its own work.
How does the connection work?
The server listens on ws://127.0.0.1:47321. Set LUMETROPE_MCP_PORT to change the port. Only local Lumetrope windows can connect.
Why is MCP hidden on a deployed web copy?
A website cannot reach an MCP server on a visitor's computer, so the badge and setup are hidden on copies served from a remote server. Use the desktop app, or serve Lumetrope from localhost.
Which tools are available?
| Tool | What it does |
|---|---|
read_scene | Read the active animation: size, fps, duration, segments, and every layer of a scene (default root) with its id, name, type, parent, in/out, visibility, lock and shape tree paths. Start here to get layer ids. |
inspect_layer | Full raw Lottie JSON of one layer plus its bounds at 'frame' and the list of animated property paths. |
list_scenes | List the root scene and every nested scene (precomp) with ids and layer counts. |
create_scene | Create an empty nested scene (precomp). With add_to_root, also place it as a layer on top of the root scene. |
set_background | Set the preview/export background colour of the active animation (null for transparent). Stored in the dotLottie manifest on export. |
list_colors | List every unique colour used by fills, strokes, solids and text, with usage counts — useful for recolouring. |
replace_color | Replace a colour everywhere (fills, strokes, keyframes, solids, text). 'tolerance' 0..1 also matches near colours. |
set_scene_settings | Change the active animation's canvas size, frame rate, duration (in frames) or name. Omitted fields are left unchanged. |
create_shape | Create a new shape layer (rect, ellipse, polygon, star or freeform path) on top of the scene, with optional fill and stroke. Returns the new layer id. |
create_solid | Create a solid colour layer covering the scene (or a given size). |
create_null | Create an invisible null layer, useful as a parent/controller for other layers. |
duplicate_layer | Duplicate a layer (with its animation) directly above the original. Returns the new id. |
delete_layer | Delete a layer. Children parented to it are unparented. |
rename_layer | Rename a layer. State machine interactions match layers by name, so keep names unique. |
reorder_layer | Move a layer in the stacking order: give an index (0 = top) or 'to' front/back/up/down. |
set_parent | Parent a layer to another layer in the same scene (child follows the parent's transform), or unparent with parent=null. |
set_layer_visibility | Show or hide a layer. |
set_layer_lock | Lock or unlock a layer for canvas editing (editor-only flag, not exported). |
set_layer_time | Set a layer's in/out points, start time offset (frames) and time stretch. |
set_blend_mode | Set a layer's blend mode. |
set_matte | Use one layer as a track matte for another (alpha, alpha_inverted, luma, luma_inverted). The matte layer is moved directly above the target and hidden from direct rendering. |
remove_matte | Remove a layer's track matte. |
precompose_layers | Move layers into a new nested scene (precomp) and replace them with one precomp layer. Returns the new scene id and layer id. |
align_layers | Align layers' bounding boxes to the scene or to the selection's combined bounds. |
distribute_layers | Evenly space the centres of 3+ layers horizontally or vertically, keeping the outermost ones in place. |
paste_layers | Insert copies of layer JSON objects (e.g. from inspect_layer) on top of a scene, assigning fresh ids and optionally offsetting them. Parent/matte links inside the pasted set are preserved. |
nudge_layers | Move layers by a scene-space delta (dx, dy) like dragging on the canvas: static positions shift; animated positions get a keyframe at 'frame'. Parented layers are handled. |
set_transform | Set transform properties of a layer (or a shape group via 'shape'). Static properties are replaced; animated ones get a keyframe at 'frame'. Rotation in degrees (clockwise), scale and opacity in percent. |
set_anchor_point | Move a layer's anchor point to a named position of its bounds (center, top_left, …) or explicit layer-space [x,y], compensating position so the layer does not move visually. |
flip_layer | Mirror a layer horizontally or vertically by negating its scale. |
set_keyframe | Add or replace a keyframe on one property at an integer frame. A static property becomes animated. Optional easing (preset name, 'hold', or [x1,y1,x2,y2]) applies to the segment starting at this keyframe. |
remove_keyframe | Remove the keyframe at a frame. When one keyframe or none remains the property becomes static. |
move_keyframe | Move one keyframe from 'frame' to frame 'to' (fails if another keyframe is already there). |
set_keyframe_easing | Set the easing of the segment that starts at the keyframe on 'frame'. Presets: linear, ease, ease_in, ease_out, ease_in_out, smooth, ease_in_back, ease_out_back, ease_in_out_back, snappy, hold — or a cubic bezier [x1,y1,x2,y2]. |
set_property | Set any property's value. Static properties are replaced; animated ones get a keyframe at 'frame' (default 0). Use this for shape items, masks ('mask:<i>') and effects ('effect:<i>') as well as transforms. |
get_property | Read one property at a frame: evaluated value, whether it is animated, whether a keyframe sits on this frame, and all keyframe frames. |
read_keyframes | List keyframes (frame, value, easing) of one property, or of every animated property of a layer when 'property' is omitted. |
clear_animation | Remove all keyframes of a property, keeping its value at 'frame' (default the first keyframe) as a static value. |
shift_keyframes | Move keyframes in time by 'by' frames (negative = earlier). Applies to one property, or all animated properties of the layer; optionally only keyframes at or after 'from_frame'. |
retime_keyframes | Scale keyframe timing around a pivot frame (scale 2 = twice as slow, 0.5 = twice as fast). |
copy_animation | Copy a layer's transform animation (all animated transform properties, or the listed ones) onto another layer, optionally offset in time. |
add_shape | Add a shape (rect, ellipse, polygon, star, path) as a new group inside an existing shape layer, on top of its other shapes. 'shape' may name a group to add into. Position is in layer space. |
remove_shape_item | Delete a shape item (geometry, paint, modifier or whole group) from a shape layer. |
set_path | Replace a path shape's bezier {v:[[x,y]...], i, o, c} (tangents relative to vertices). Animated paths get a keyframe at 'frame'. |
add_trim_path | Add a trim-paths modifier (start/end in %, offset in degrees) affecting all paths before it in the layer or group. Animate 'end' 0→100 for a draw-on effect. |
add_round_corners | Add a round-corners modifier with the given radius to the layer or group. |
add_repeater | Add a repeater that copies everything above it N times, each copy offset by position/rotation/scale, fading from start_opacity to end_opacity. |
update_shape_item | Update a shape item: animatable 'props' by friendly name (size, roundness, color, opacity, width, start, end, …) plus name, hidden, direction (1 or 3), fill_rule (non_zero|even_odd), line_cap (butt|round|square), line_join (miter|round|bevel), miter_limit, trim_mode (simultaneous|individual). |
reorder_shape | Move a shape item to a new index within its parent list (0 = top). |
set_fill | Set (or add) the solid fill of a shape layer or group: colour and opacity %. Animated colours get a keyframe at 'frame'. |
set_stroke | Set (or add) the stroke of a shape layer or group: colour, width, opacity, line_cap, line_join, dash [dash, gap]. |
set_gradient | Give a shape layer or group a linear or radial gradient fill/stroke. stops: [{offset 0..1, color, opacity 0..1?}]. start/end points in layer space default to the shape's bounds. |
remove_paint | Remove fills, strokes (solid or gradient) or both from a shape layer or group. |
add_mask | Add a mask to a layer: rect/ellipse (position + size in layer space, default the layer bounds) or a bezier path. Modes: add, subtract, intersect, lighten, darken, difference, none. |
update_mask | Change a mask's mode, inversion, opacity, name or path (path keyframes via set_keyframe with shape 'mask:<i>'). |
remove_mask | Remove a mask from a layer. |
add_effect | Add a layer effect: drop_shadow (color, opacity %, direction °, distance, softness, shadow_only), gaussian_blur (blurriness, dimensions both|horizontal|vertical), fill (color, opacity %), tint (black, white, amount %), tritone (highlights, midtones, shadows, blend %). |
update_effect | Update parameters of a layer effect by index (see list_effects). Animated parameters get a keyframe at 'frame'; 'enabled' toggles the effect. |
remove_effect | Remove a layer effect by index. |
list_effects | List a layer's effects with their parameters. |
create_text | Create a text layer. Position is the text anchor (baseline centre for centred text); give 'box' [w,h] for wrapped paragraph text. |
set_text | Change a text layer's content (use \r or \n for line breaks). |
set_text_style | Change font, size, colours, stroke, justification, tracking, line height or caps of a text layer. |
list_slots | List slots (themeable properties) of the active animation with type, current value and how many properties are bound. |
create_slot | Expose a property as a themeable slot (dotLottie themes override slots). Binds the property and records its current value as the slot default. |
unlink_slot | Unbind a property from its slot (the slot is deleted when nothing else uses it). |
update_slot_value | Change a slot's default value; every bound property updates. |
list_themes | List project themes with their rule counts. |
add_theme | Create a theme (a set of slot overrides exported to the dotLottie t/ folder). |
update_theme_rule | Set (or with remove=true delete) a theme's override for one slot. Give 'value', or 'keyframes' [{frame, value}] for an animated override. |
remove_theme | Delete a theme. |
select_theme | Preview the animation with a theme applied (null for no theme). |
list_segments | List named segments (markers) with start and end frames. State machine playback states play segments by name. |
add_segment | Add a named segment (marker) from 'start' to 'end' frame. |
update_segment | Rename or retime a segment. |
remove_segment | Delete a segment. |
list_state_machines | List the project's state machines. |
add_state_machine | Create an empty state machine. Returns its id. |
remove_state_machine | Delete a state machine. |
rename_state_machine | Rename a state machine. |
read_state_machine | Return a state machine as dotLottie spec JSON (initial, states, interactions, inputs). |
add_state | Add a state: a playback state (plays the animation or a named segment with loop/mode/speed) or the single global state (type 'global') whose transitions are checked from any state. The first playback state becomes initial. |
update_state | Change a state's settings (null removes an optional field). Renaming updates transitions, interactions and the initial state. |
remove_state | Delete a state and every transition/interaction that refers to it. |
set_initial_state | Choose the state the machine starts in. |
add_transition | Add a transition from one state to another, optionally guarded by input conditions and tweened over a duration. |
update_transition | Update the transition at 'index' in state 'from'. |
remove_transition | Delete the transition at 'index' in state 'from'. |
add_input | Add an input variable: boolean, numeric, string or event (events have no value). |
update_input | Rename an input or change its type/default value. Renames update guards and actions. |
remove_input | Delete an input along with guards and actions that use it. |
add_interaction | Wire a user/playback event (Click, PointerDown/Up/Enter/Exit/Move on an optional layer, OnComplete/OnLoopComplete of a state) to actions. |
update_interaction | Update the interaction at 'index'. |
remove_interaction | Delete the interaction at 'index'. |
import_svg | Import SVG markup as a new editable shape layer (paths, fills, strokes and gradients), centred in the scene unless a position is given. |
import_lottie | Import another Lottie animation (JSON string or object) as a nested scene layer; its assets are merged with remapped ids. |
import_image | Embed a PNG or JPEG (data: URL) as an image asset and add an image layer centred in the scene. |
apply_motion_preset | Animate a layer with a preset (fade_in/out, scale_in/out, pop, slide_in/out_left/right/up/down, spin, bounce, pulse, shake, wiggle, float, blink) starting at start_frame for duration_frames. Values are relative to the layer's current transform; 'intensity' scales distances/angles. |
stagger_layers | Apply the same motion preset to several layers, each starting 'delay_frames' after the previous (in the order given). |
get_editor_state | Current editor state: file name, mode, playhead frame, selected layers, scene being edited, and whether there are unsaved versions. |
get_frame_image | Render a frame of the active animation to a PNG so you can see the result. Use it after edits to verify layout, colours and motion. |
set_current_frame | Move the editor's playhead (also the frame new keyframes are added at by the UI). |
undo | Undo the last change. |
redo | Redo the last undone change. |
save_version | Save the current document as a named version in the local history. |
list_versions | List saved versions (newest first) on the current branch. |
restore_version | Restore a saved version by id (from list_versions). Unsaved work is first kept as an Auto-saved version. |
preview_state_machine | Start running a state machine in the preview so you can test it with the state_machine_* tools. |
state_machine_input | Set an input of the running state machine (boolean, number or string) or fire an event input. Returns the new state. |
state_machine_pointer | Simulate a pointer event (click, down, up, move, enter, exit) at scene coordinates on the running state machine. |
state_machine_advance | Advance the running state machine by some seconds so segments can finish and OnComplete can fire. Returns the state. |
stop_state_machine_preview | Stop the running state machine preview. |