MCP server

Imported from the repository

This page is generated from docs/mcp.md. Edit it there.

The OpenBone MCP server lets an AI agent create and edit animations with the same operations the editor uses, check its work with rendered frames and state-machine runs, and export the result. Every editing op in packages/core is a tool automatically, so the agent can do anything the editor can.

• Running it
• Connecting a client
• Tools
• Resources and prompts
• Live editing

Running it

Command	What it does
pnpm mcp	stdio server, plus the live bridge on ws://127.0.0.1:7717
pnpm mcp --project ~/anim/hero.obone	opens (or creates) a project at startup
pnpm mcp --http 7718	streamable HTTP at http://127.0.0.1:7718/mcp
pnpm mcp --no-bridge	no WebSocket bridge

Connecting a client

The repository ships .mcp.json, so Claude Code picks up the openbone server automatically. For other clients:

{ "mcpServers": { "openbone": { "command": "npx", "args": ["-y", "@openbone/mcp"] } } }

From a checkout instead of npm:

{ "mcpServers": { "openbone": { "command": "pnpm", "args": ["exec", "tsx", "/path/to/OpenBone/packages/mcp/src/bin.ts"] } } }

npx -y @openbone/mcp --http 7718 and the other options above work the same way.

Then ask, for example: “Create a project at ~/anim/robot.obone: a robot with IK arms, an idle and a wave animation, and a state machine that waves when clicked.”

Tools

Group	Tools
Project	new_project, open_project, save_project (projects with a path autosave after every edit), get_summary, get_document, validate, undo, redo, import_image, import_audio (WAV/MP3/OGG/FLAC, its length read from the file; creates a sound too), get_guide
Art prep	process_image: run ops on a picture and save it as a PNG, imported as a new image (importAs) or replacing one in place (replace). Ops: keyColor (remove a flat background colour everywhere, with soft edges and no fringe), differenceMatte (cut out what differs from a copy with the object painted out, e.g. a tree to animate on its own layer), trim, crop, resize, flip, featherEdges (so tiled copies overlap without seams), keepLargest. Returns box, where the result sat in the input, for placing it exactly. PNG metadata such as C2PA content credentials is dropped on load
Editing	One tool per core op, for example add_bone, update_bone, add_slot, add_shape, add_region, add_mesh, auto_weights, add_ik_constraint, create_animation, set_keys (merges keys; replace: true makes the timeline exactly the given keys), add_event_key, create_state_machine, add_input, add_state, add_transition, add_listener, add_script, attach_script, set_atlas. pnpm cli ops lists them all
Audio	add_sound, add_bus, set_audio_mix, add_audio_key, set_event_sound, set_state_sound
Rigging helpers	trace_mesh (trace a region into a mesh, or re-trace a mesh where it sits and bind it again to the same bones; tolerance sets how closely the outline follows the edge), set_weights_in_area (set the bone weights of every vertex inside a box or polygon of the setup pose, with a soft blend edge: pin feet to the legs, a hem to the skirt), pose_bones (the Pose tool: bend a bone and its parents so its tip reaches a point), smooth_weights, prune_weights, lip_sync (key a mouth slot to a WAV)
Atlas	pack_atlas: pack every image into atlas pages, with rotate, scale (a fraction or "auto"), stripWhitespace, polygons, premultipliedAlpha, page size rules (maxWidth/maxHeight, minWidth/minHeight, square, multipleOf4), alias, ignoreBlank, alphaThreshold, edgePadding, duplicatePadding, bleed, runtime metadata (filterMin, filterMag, wrapX, wrapY, pixelFormat), pageFormat (png or jpeg + jpegQuality), resample and debug. export_file takes the same settings as atlas, plus scales (one data file + page set per scale) for the atlas format
Export	export_file: everything the Export dialog makes (obone — embed: true puts every image and sound inside, so the file opens on its own anywhere, also in the web editor —, json, obonb, atlas, png, jpeg, apng, gif, psd, avi, mov, mp4, webm, spritesheet, web), from an animation or a state machine run. Videos carry the sound the run plays (audio: false leaves it out); mp4 / webm and MP3/OGG sound use ffmpeg from the PATH
Checking the work	render_frame (a PNG with bones and hit boxes overlaid), render_gif, simulate_state_machine (a log of states, events, inputs, audio commands and script output for steps like setInputs, fire, pointer, advance), inspect_pose (bone world positions and rotations), get_stats (bones, vertices, triangles, clipping masks, estimated draw calls)

pack_atlas and export_file run the same code as the editor’s Export dialog and the CLI (buildAtlas and exportFile), so all three produce the same files.

Resources and prompts

• Resources: openbone://guide, openbone://document, openbone://summary
• Prompts: rig_character, interactive_button

Live editing

Click ⚡ Connect MCP in the editor to watch an agent work. The server sends its document, and from then on both sides exchange ops:

sequenceDiagram
    participant A as AI agent
    participant S as MCP server
    participant E as Editor
    E->>S: connect (ws://127.0.0.1:7717)
    S->>E: current document
    A->>S: tool call (add_bone, set_keys, …)
    S->>E: op (with generated ids filled in)
    E->>S: op from the user's own edit
    E->>S: undo / redo
    S-->>E: resync, if an op failed

Note

The server is the source of truth: undo and redo in the editor are forwarded to it, and if an op fails the editor is resynced from the server’s document.