unreal-animation-mcp

Animation data inspector and editor for Unreal Engine AI development via Model Context Protocol.

Inspect, search, and edit animation sequences, montages, blend spaces, animation blueprints, skeletons, and skeletal meshes — 62 tools total.

Why?

Animation data in Unreal is deeply nested and spread across many asset types — sequences hold notifies, curves, and bone tracks; montages add sections and slots on top; blend spaces map animations to parameter grids; and Animation Blueprints wire it all together through state machines, transitions, and blend nodes. AI agents can't see any of this from C++ alone. This server exposes the full animation stack as structured data so agents can inspect, search, audit, and edit animation assets alongside the rest of your project.

Complements (does not replace):

• unreal-source-mcp — Engine-level source intelligence (full UE C++ and HLSL)
• unreal-project-mcp — Project-level source intelligence (your C++ code)
• unreal-editor-mcp — Build diagnostics and editor log tools (Live Coding, error parsing, log search)
• unreal-blueprint-mcp — Blueprint graph reading (nodes, pins, connections, execution flow)
• unreal-blueprint-reader — C++ editor plugin that serializes Blueprint graphs to JSON for AI tooling
• unreal-material-mcp — Material graph intelligence and editing (expressions, connections, parameters, instances, graph manipulation)
• unreal-config-mcp — Config/INI intelligence (resolve inheritance chains, search settings, diff from defaults, explain CVars)
• unreal-niagara-mcp — Niagara VFX intelligence and editing (emitters, modules, HLSL generation, procedural creation, 70 tools)
• unreal-api-mcp by Nico Bailon — API surface lookup (signatures, #include paths, deprecation warnings)

Together these servers give AI agents full-stack UE understanding: engine internals, API surface, your project code, build/runtime feedback, Blueprint graph data, config/INI intelligence, material graph inspection + editing, animation data inspection + editing, and Niagara VFX inspection + creation.

Prerequisites

• AnimationMCPReader plugin installed in your UE project (unreal-animation-reader) — required for C++-backed tools (montage sections, blendspace samples, ABP state machines/transitions/blend nodes, notify time/duration, bone track keys)
• Python Remote Execution enabled in the editor: Edit > Project Settings > search "remote" > under Python Remote Execution, check "Enable Remote Execution?"

Quick Start

Install from GitHub

uvx --from git+https://github.com/tumourlove/unreal-animation-mcp.git unreal-animation-mcp

Claude Code Configuration

Add to your project's .mcp.json:

{
  "mcpServers": {
    "unreal-animation": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/tumourlove/unreal-animation-mcp.git", "unreal-animation-mcp"],
      "env": {
        "UE_PROJECT_PATH": "D:/Unreal Projects/YourProject"
      }
    }
  }
}

Environment Variables

Variable	Required	Description
UE_PROJECT_PATH	Yes	Path to the UE project root (containing the .uproject file)
UE_EDITOR_PYTHON_PORT	No	TCP port for editor Python commands (default: 6776)
UE_MULTICAST_GROUP	No	UDP multicast group for editor discovery (default: 239.0.0.1)
UE_MULTICAST_PORT	No	UDP multicast port for editor discovery (default: 6766)
UE_MULTICAST_BIND	No	Local interface to bind multicast listener (default: 127.0.0.1)

How It Works

1. Editor Discovery — Discovers the running UE editor via UDP multicast (the same protocol as UE's built-in remote_execution.py). Opens a TCP command channel to execute Python in the editor.

2. Helper Upload — Uploads animation_helpers.py to {project}/Saved/AnimationMCP/ on first use. The helper module wraps unreal.AnimationLibrary and related APIs for inspection, editing, and search operations.

3. Plugin Bridge — For advanced operations, sends Python commands that call AnimationMCPReaderLibrary static functions from the companion C++ plugin. The plugin serializes animation graph data to JSON strings.

4. Serving — FastMCP server exposes 62 tools over stdio. Claude Code manages the server lifecycle automatically.

No database, no indexing — all data comes live from the running editor. The server is stateless; animation data is read on demand from whatever assets are loaded.

Adding to Your Project's CLAUDE.md

## Animation Data (unreal-animation MCP)

Use `unreal-animation` MCP tools to inspect, edit, and search animation data —
sequences, montages, blend spaces, ABPs, skeletons, and meshes. Requires
**AnimationMCPReader** plugin and **Python Remote Execution** enabled in editor.

| Category | Tools | When |
|----------|-------|------|
| Sequence Inspect | `get_anim_sequence_info`, `get_anim_notifies`, `get_anim_curves`, `get_bone_tracks` | Understand an animation's properties, notifies, curves, bone data |
| Montage Inspect | `get_montage_info`, `get_montage_sections`, `get_montage_slots` | Read montage structure, sections, slot assignments |
| BlendSpace | `get_blendspace_info`, `get_blendspace_samples` | Read blend space parameters and sample points |
| ABP Inspect | `get_abp_info`, `get_abp_state_machines`, `get_abp_transitions` | Read AnimBP graph structure, state machines, transitions |
| Notify Edit | `add_notify`, `add_notify_state`, `remove_notifies`, `set_notify_time` | Add/remove/move animation notifies |
| Montage Edit | `add_montage_section`, `set_section_next`, `set_montage_blend` | Edit montage sections and blend settings |
| Search | `search_animations`, `search_by_notify`, `audit_notifies` | Find animations by type/folder, audit notify usage |

**Asset paths (no extension):**
- Project `Content/`: `/Game/Path/To/Asset`
- Project `Plugins/`: `/PluginName/Path/To/Asset`
- Engine plugins: `/PluginName/Path/To/Asset`

Tools (62)

Inspection (23)

• AnimSequence: get_anim_sequence_info, get_anim_notifies, get_anim_curves, get_bone_tracks, get_bone_pose_at_time, get_sync_markers
• AnimMontage: get_montage_info, get_montage_sections, get_montage_slots
• BlendSpace: get_blendspace_info, get_blendspace_samples
• Skeleton/Mesh: get_skeleton_info, get_skeletal_mesh_info
• AnimBlueprint: get_abp_info, get_abp_graphs, get_abp_nodes, get_abp_asset_overrides, get_abp_state_machines, get_abp_state_info, get_abp_transitions, get_abp_blend_nodes, get_abp_linked_layers

Editing (31)

• Notifies: add_notify, add_notify_state, remove_notifies, add_notify_track, remove_notify_track, set_notify_time, set_notify_duration
• Curves: add_curve, add_curve_keys, remove_curve
• Sync Markers: add_sync_marker, remove_sync_markers
• Properties: set_root_motion, set_rate_scale, set_additive_type
• Virtual Bones: add_virtual_bone, remove_virtual_bones
• Montage: set_montage_blend, add_montage_section, delete_montage_section, set_section_next, set_section_time
• BlendSpace: add_blendspace_sample, edit_blendspace_sample, delete_blendspace_sample
• Bone Tracks: add_bone_track, remove_bone_track, set_bone_track_keys
• Misc: copy_notifies, add_meta_data, remove_meta_data

Search & Analysis (8)

• search_animations, search_by_notify, search_by_curve, search_by_slot
• audit_notifies, audit_blendspace, compare_animations, get_animation_summary

Development

# Clone and install
git clone https://github.com/tumourlove/unreal-animation-mcp.git
cd unreal-animation-mcp
uv sync

# Run tests
uv run pytest -v

# Run server locally
uv run unreal-animation-mcp

Requirements

• Python 3.11+
• uv (recommended) or pip
• Unreal Engine 5.x with Python plugin and Remote Execution enabled
• AnimationMCPReader C++ plugin

License

MIT