unreal-mcp skill

Unreal Engine MCP Skill

Companion skill for the unreal-engine entry in the Hermes MCP catalog. The MCP server (Epic's official, experimental "Unreal MCP" plugin, internal id ModelContextProtocol) runs INSIDE the Unreal Editor process and exposes editor functionality as typed tools. This skill teaches how to drive it well: discovering the live tool surface, sequencing calls safely, translating plain-English asks into scenes that actually look good, and verifying work visually. The user should never need to touch the editor beyond launching it.

When to Use

Use when the user wants anything done in Unreal Engine: build or dress a level, spawn/move/delete actors, set up lighting and atmosphere, create or tune material instances, frame a camera shot, capture screenshots or renders, import assets, inspect the scene or UI, run automation tests, or script the editor. Works for single actions ("make the sun golden hour") and for complete multi-step projects ("build me a moody forest clearing with a campfire and render a shot of it").

Don't use for: DCC-style mesh modeling/sculpting (model in Blender and import the result), or for editing Unreal C++ project source (that's normal code work — use the terminal; this skill is about the live editor).

Prerequisites

Two halves, in this order: the editor side must be up before Hermes connects.

One-time, editor side

installed and its license accepted — the editor exits on first launch without it; see pitfalls.)

1. Unreal Editor 5.8+ with a project open. (macOS: full Xcode must be

dependency auto-enables). Restart the editor when prompted.

1. Edit > Plugins — enable Unreal MCP (its Toolset Registry

AllToolsets plugin in the same Plugins browser. Unreal MCP ships NO tools itself — AllToolsets provides the shipped toolsets (SceneTools, ActorTools, MaterialInstanceTools, ObjectTools, …); skip it and the server connects but the agent has nothing to call.

1. The typed toolsets ship separately from the server: also enable the

Auto Start Server. Default bind is http://127.0.0.1:8000/mcp (port/path configurable in the same panel; server name is unreal-mcp). To start manually instead, run ModelContextProtocol.StartServer in the editor console (backtick key).

1. Edit > Editor Preferences > General > Model Context Protocol — enable

One-time, Hermes side

hermes mcp install unreal-engine

This writes the mcpservers.unreal-engine HTTP entry pointing at http://127.0.0.1:8000/mcp and probes the live server for its tools. Run it while the editor + server are up so the probe sees the real surface. If the user changed port/path in Editor Preferences, edit the url in ~/.hermes/config.yaml under mcpservers.unreal-engine to match.

Do NOT use ModelContextProtocol.GenerateClientConfig for Hermes — that writes .mcp.json-style files for Claude Code/Cursor/etc. Hermes connects from config.yaml via the catalog entry.

Every session

server started (Output Log shows the bind address, or run ModelContextProtocol.StartServer manually).

1. Launch Unreal Editor, wait for the project to finish loading; confirm the

they're missing: editor wasn't up first — start it, then open a new Hermes session.

1. Start the Hermes session. Tools register as mcpunrealengine_*. If

come back.

1. Sanity check: call mcpunrealenginelisttoolsets and confirm toolsets

The Tool Surface: Discovery, Not a Fixed List

By default the plugin runs in tool-search mode: tools/list returns only three meta-tools, and every real tool is reached through them. Through Hermes they appear as:

The discovery walk, always in this order:

(the surface is project-dependent: enabled plugins, Game Feature Plugins, and any custom toolsets all contribute). Names come back FULLY QUALIFIED (editortoolset.toolsets.scene.SceneTools, EditorToolset.EditorAppToolset) — use them verbatim as toolsetname.

1. list_toolsets → see what capability groups this project actually has

schemas. Never guess parameter names — schemas are the contract.

1. describe_toolset on the group you need → read the real parameter

(find_actors, not the dotted form), and arguments matching the schema.

1. call_tool with the qualified toolset name, the SHORT tool name

Cache what you learn for the session; re-list only after the editor side changes (new plugin enabled, toolset authored, RefreshTools run).

The alternative eager mode (Enable Tool Search off in Editor Preferences) advertises every tool as its own mcpunrealengine_{tool} entry. Discovery then happens at hermes mcp install/configure time instead. Tool-search mode is the default and what this skill assumes; it also keeps schema tokens out of every API call, so prefer it.

See references/tool-surface.md for the shipped toolset catalog, authoring custom toolsets, and the full plugin configuration/console-command reference.

Operating Loop

Every Unreal task follows the same loop:

touching anything. Never assume an empty or default level. In an unfamiliar project, also check for project-registered Agent Skills (call_tool → AgentSkillToolset.ListSkills): a matching project skill's instructions override this skill's generic defaults.

1. Inspect first. List toolsets, then query the scene/level state before

The server executes tools serially on the game thread — a big monolithic operation freezes the editor UI until it finishes and risks client timeouts. Exception: for loops over 5+ homogeneous operations, ONE ProgrammaticToolset.executetoolscript call batches them server-side without breaking the serial rule (references/advanced-workflows.md).

1. Act in small, single-purpose calls. One logical step per call_tool.

mcpunrealengine_* calls in one turn — Hermes runs batched calls concurrently, and parallel calls against the game thread deadlock or fail. Strictly one call, await result, next call. This overrides the general parallel-tool-calls guidance.

1. NEVER issue overlapping calls. Do not batch multiple

widget creation) report success/failure in the response body with no protocol-level exception. Anything that isn't an explicit success is a stop-and-diagnose, not a shrug. After property writes, read the value back — several write paths silently no-op (see pitfalls).

1. Read every result. Many tools (Blueprint compiles, material edits,

by querying the actors/properties you changed, and capture a viewport screenshot when composition matters (see references/tool-surface.md for the capture options; vision_analyze the image — you are the art director, judge it).

1. Verify visually and structurally. After each milestone, confirm state

saved; an editor crash loses everything since the last save, and MCP edits are not reliably undoable. Save before AND after any bulk change, and after every milestone.

1. Save often. Editor edits are in-memory until packages/levels are

locations of captures/renders.

1. Report concretely. Actor labels, asset paths (/Game/...), file

Rules of the world while you work:

degrees (Rotator: Roll around X, Pitch around Y, Yaw around Z). Human eye height ≈ 165 cm; a door ≈ 210×90 cm. Full tables in references/scene-craft.md.

• Units are centimeters; axes are Z-up, X-forward; rotations are

project content, /Engine/BasicShapes/Cube.Cube for engine primitives.

• Content paths use long package names: /Game/Folder/Asset.Asset for