UE Audio MCP Plugin — TCP Control

Drive the C++ TCP server inside Unreal Editor. Each command is flat JSON (action plus its params at the top level), framed with a 4-byte big-endian length prefix, on 127.0.0.1:9877. Commands run on the game thread.

Connection

# Python SDK
from ue_audio_mcp.ue5_connection import get_ue5_connection
conn = get_ue5_connection()
resp = conn.send_command({"action": "ping"})

# Raw TCP
python3 -c "
import socket, struct, json
s = socket.socket(); s.settimeout(5); s.connect(('127.0.0.1', 9877))
p = json.dumps({'action':'ping'}).encode()
s.sendall(struct.pack('>I', len(p)) + p)
r = s.recv(4); l = struct.unpack('>I', r)[0]; print(json.loads(s.recv(l)))
"

Commands

The plugin registers 48 commands. Params marked ? are optional, with defaults in parentheses; every response also carries status (and message on errors). The source of truth is the RegisterCommand calls in ue5_plugin/UEAudioMCP/Source/UEAudioMCP/Private/UEAudioMCPModule.cpp; each command reads its params in Private/Commands/*.cpp.

System

Builder lifecycle

Graph I/O

Nodes

Build, audition & editor

Variables (UE 5.7+)

Presets

Query & export

Blueprint & assets

Blueprint builder

World setup

Actor & camera

Allowlisted functions: PlaySound2D, PlaySoundAtLocation, SpawnSoundAtLocation, SpawnSound2D, SetSoundMixClassOverride, ClearSoundMixClassOverride, PushSoundMixModifier, PopSoundMixModifier, SetGlobalPitchModulation, SetGlobalListenerFocusParameters, PlayDialogue2D, PlayDialogueAtLocation, SpawnDialogue2D, SpawnDialogueAtLocation, GetPlayerCameraManager, GetPlayerController, GetPlayerPawn.

class_filter values: Blueprint, WidgetBlueprint, AnimBlueprint, MetaSoundSource, MetaSoundPatch, SoundWave, SoundCue, SoundAttenuation, SoundClass, SoundConcurrency, SoundMix, ReverbEffect.

Source Builder Graph Pins

create_builder with Source gives __graph__ three built-in pins: OnPlay (trigger in), OnFinished (trigger out) and Audio:0 (mono audio out). Wire the sound into Audio:0: add_graph_output adds an extra, custom output, not the one you hear. __graph__ is the boundary sentinel, not a real node.

Node Types and Pin Names

add_node accepts a display name from the plugin's small built-in map (e.g. Sine, Biquad Filter) or any full class name containing ::. Take class names and exact, typed pin names from the engine-synced catalogue — src/ue_audio_mcp/knowledge/metasound_catalogue.json, or the ms_node_info and ms_search_nodes tools — and use list_node_classes against the live editor for anything missing.

Common nodes (from the catalogue):

• Sine / Saw / Triangle (UE::Sine::Audio, UE::Saw::Audio, UE::Triangle::Audio): in Enabled, Bi Polar, Frequency, Modulation, Sync, Phase Offset, Glide, Type; out Audio
• Square (UE::Square::Audio): in Enabled, Bi Polar, Frequency, Modulation, Sync, Phase Offset, Glide, Type, Pulse Width; out Audio
• AD Envelope (Audio) (AD Envelope::AD Envelope::Audio): in Trigger, Attack Time, Decay Time, Attack Curve, Decay Curve, Looping, Hard Reset; out On Trigger, On Done, Out Envelope
• ADSR Envelope (Float) (ADSR Envelope::ADSR Envelope::Float): in Trigger Attack, Trigger Release, Attack Time, Decay Time, Sustain Level, Release Time, Attack Curve, Decay Curve, Release Curve, Hard Reset; out On Attack Triggered, On Decay Triggered, On Sustain Triggered, On Release Triggered, On Done, Out Envelope
• Biquad Filter (UE::Biquad Filter::Audio): in In, Cutoff Frequency, Bandwidth, Gain, Type; out Out
• Wave Player (Mono) (UE::Wave Player::Mono): in Play, Stop, Wave Asset, Start Time, Pitch Shift, Loop, Loop Start, Loop Duration, Maintain Audio Sync; out On Play, On Finished, On Nearly Finished, On Looped, On Cue Point, Cue Point ID, Cue Point Label, Loop Percent, Playback Location, Playback Time, Out Mono
• Multiply (Audio) (UE::Multiply::Audio): in PrimaryOperand, AdditionalOperands; out Out
• Multiply (Audio by Float) (UE::Multiply::Audio by Float): in PrimaryOperand, AdditionalOperands; out Out
• Map Range (Float) (MapRange::MapRange::Float): in In, In Range A, In Range B, Out Range A, Out Range B, Clamped; out Out Value

Example Workflows

Simple Sine → Output

{"action":"create_builder", "asset_type":"Source", "name":"MySine"}
{"action":"add_node", "id":"osc", "node_type":"UE::Sine::Audio"}
{"action":"set_default", "node_id":"osc", "input":"Frequency", "value":440}
{"action":"connect", "from_node":"osc", "from_pin":"Audio", "to_node":"__graph__", "to_pin":"Audio:0"}
{"action":"build_to_asset", "name":"MySine", "path":"/Game/Audio/MCP"}

Filtered Synth with Envelope

{"action":"create_builder", "asset_type":"Source", "name":"FilteredSynth"}
{"action":"add_graph_input", "name":"Cutoff", "type":"Float", "default":"2000.0"}
{"action":"add_node", "id":"osc", "node_type":"UE::Saw::Audio"}
{"action":"add_node", "id":"filt", "node_type":"UE::Biquad Filter::Audio"}
{"action":"add_node", "id":"env", "node_type":"AD Envelope::AD Envelope::Audio"}
{"action":"add_node", "id":"amp", "node_type":"UE::Multiply::Audio"}
{"action":"connect", "from_node":"osc", "from_pin":"Audio", "to_node":"filt", "to_pin":"In"}
{"action":"connect", "from_node":"__graph__", "from_pin":"Cutoff", "to_node":"filt", "to_pin":"Cutoff Frequency"}
{"action":"connect", "from_node":"__graph__", "from_pin":"OnPlay", "to_node":"env", "to_pin":"Trigger"}
{"action":"connect", "from_node":"filt", "from_pin":"Out", "to_node":"amp", "to_pin":"PrimaryOperand"}
{"action":"connect", "from_node":"env", "from_pin":"Out Envelope", "to_node":"amp", "to_pin":"AdditionalOperands"}
{"action":"connect", "from_node":"amp", "from_pin":"Out", "to_node":"__graph__", "to_pin":"Audio:0"}
{"action":"connect", "from_node":"env", "from_pin":"On Done", "to_node":"__graph__", "to_pin":"OnFinished"}
{"action":"build_to_asset", "name":"FilteredSynth", "path":"/Game/Audio/MCP"}

Project Scan & Export

{"action":"list_assets", "class_filter":"Blueprint"}
{"action":"scan_blueprint", "asset_path":"/Game/BP_Player", "audio_only":true}
{"action":"list_assets", "class_filter":"MetaSoundSource"}
{"action":"export_metasound", "asset_path":"/Game/Audio/MS_Gunshot"}

Or batch: python scripts/scan_project.py --full-export --import-db --rebuild-embeddings

Gotchas

• Call create_builder before any node or connection command. Builder state is global: one active builder at a time.
• Asset paths must start with /Game/ or /Engine/ and must not contain ...
• Audio and Float pins don't cross-connect. Pick the matching node variant, e.g. Multiply (Audio by Float) to scale audio by a float.
• TCP drops after ~17 rapid commands — reconnect with a progressive delay.

Source Files

• Command registration: ue5_plugin/UEAudioMCP/Source/UEAudioMCP/Private/UEAudioMCPModule.cpp
• Command handlers: ue5_plugin/UEAudioMCP/Source/UEAudioMCP/Private/Commands/
• Builder state, __graph__ pins, node-type resolution: ue5_plugin/UEAudioMCP/Source/UEAudioMCP/Private/AudioMCPBuilderManager.cpp
• TCP server: ue5_plugin/UEAudioMCP/Source/UEAudioMCP/Private/AudioMCPTcpServer.cpp
• Python tools: src/ue_audio_mcp/tools/
• Node catalogue: src/ue_audio_mcp/knowledge/metasound_catalogue.json (engine-synced) and metasound_nodes.py

$ARGUMENTS