Unreal MCP Skill for Hermes Agent: UE5 Editor Automation

The Unreal MCP skill is the companion guide for the unreal-engine entry in the Hermes MCP catalog. It teaches an agent to drive Epic's experimental Unreal MCP plugin, which runs inside the Unreal Editor process and exposes editor functionality as typed tools. Reach for it when you want scenes, actors, lighting, materials, cameras, renders, or editor automation handled from a Hermes session without touching the editor beyond launching it.

What it does

The MCP server is Epic's official, experimental "Unreal MCP" plugin, internal id ModelContextProtocol. It lives inside the editor and publishes editor capabilities as typed tools. The skill is not the server: it is the operating discipline on top. It covers how to discover the live tool surface, sequence calls so the game thread does not deadlock, translate a plain-English brief into a scene that reads well, and verify the result visually.

In practice that means you can ask for a single action ("make the sun golden hour") or a whole project ("build me a moody forest clearing with a campfire and render a shot of it"). The agent inspects the level, plans the build, places and adjusts actors, sets lighting and atmosphere, tunes material instances, frames a camera, captures screenshots or renders, imports assets, inspects the scene or UI, runs automation tests, or scripts the editor.

Before you start

There are two halves, and the order matters: the editor side must be up before Hermes connects.

One-time, editor side

Unreal Editor 5.8+ with a project open. On macOS, full Xcode must be installed and its license accepted; the editor exits on first launch without it.
Open Edit > Plugins and enable Unreal MCP. Its Toolset Registry dependency auto-enables. Restart the editor when prompted.
In the same Plugins browser, also enable the AllToolsets plugin. The typed toolsets ship separately from the server. Unreal MCP ships no tools itself; AllToolsets provides the shipped toolsets (SceneTools, ActorTools, MaterialInstanceTools, ObjectTools, and others). Skip it and the server connects but the agent has nothing to call.
Go to Edit > Editor Preferences > General > Model Context Protocol and enable Auto Start Server. The default bind is http://127.0.0.1:8000/mcp; port and path are configurable in the same panel, and the server name is unreal-mcp. To start manually instead, run ModelContextProtocol.StartServer in the editor console (backtick key).

One-time, Hermes side

hermes mcp install unreal-engine

This writes the mcp_servers.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 and server are up so the probe sees the real surface. If the port or path was changed in Editor Preferences, edit the url in ~/.hermes/config.yaml under mcp_servers.unreal-engine to match.

Do not use ModelContextProtocol.GenerateClientConfig for Hermes. That writes .mcp.json-style files for Claude Code, Cursor, and similar clients. Hermes connects from config.yaml via the catalog entry.

Every session

Launch Unreal Editor and wait for the project to finish loading. Confirm the server started: the Output Log shows the bind address, or run ModelContextProtocol.StartServer manually.
Start the Hermes session. Tools register as mcp_unreal_engine_*. If they are missing, the editor was not up first; start it, then open a new Hermes session.
Sanity check by calling mcp_unreal_engine_list_toolsets and confirming toolsets come back.

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:

Hermes tool	Purpose
`mcp_unreal_engine_list_toolsets`	Names + descriptions of every registered toolset
`mcp_unreal_engine_describe_toolset`	Full JSON schemas for one named toolset's tools
`mcp_unreal_engine_call_tool`	Invoke a named tool with arguments, get the result

The discovery walk always runs in this order:

list_toolsets shows which capability groups this project actually has. The surface is project-dependent: enabled plugins, Game Feature Plugins, and any custom toolsets all contribute. Names come back fully qualified (editor_toolset.toolsets.scene.SceneTools, EditorToolset.EditorAppToolset); use them verbatim as toolset_name.
describe_toolset on the group you need gives you the real parameter schemas. Never guess parameter names; schemas are the contract.
call_tool with the qualified toolset name, the short tool name (find_actors, not the dotted form), and arguments matching the schema.

Cache what you learn for the session. Re-list only after the editor side changes: a new plugin enabled, a toolset authored, or RefreshTools run.

The alternative eager mode (turn Enable Tool Search off in Editor Preferences) advertises every tool as its own mcp_unreal_engine_{tool} entry. Discovery then happens at hermes mcp install or 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.

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

Operating loop

Every Unreal task follows the same loop.

Inspect first. List toolsets, then query the scene or level state before touching anything. Never assume an empty or default level. In an unfamiliar project, also check for project-registered Agent Skills (call_tool to AgentSkillToolset.ListSkills); a matching project skill's instructions override this skill's generic defaults.
Act in small, single-purpose calls. One logical step per call_tool. The server executes tools serially on the game thread, so a big monolithic operation freezes the editor UI until it finishes and risks client timeouts. Exception: for loops over 5+ homogeneous operations, one ProgrammaticToolset.execute_tool_script call batches them server-side without breaking the serial rule (references/advanced-workflows.md).
Never issue overlapping calls. Do not batch multiple mcp_unreal_engine_* calls in one turn. Hermes runs batched calls concurrently, and parallel calls against the game thread deadlock or fail. Strictly one call, await the result, next call. This overrides the general parallel-tool-calls guidance.
Read every result. Many tools (Blueprint compiles, material edits, widget creation) report success or failure in the response body with no protocol-level exception. Anything that is not 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).
Verify visually and structurally. After each milestone, confirm state by querying the actors and properties you changed, and capture a viewport screenshot when composition matters (see references/tool-surface.md for the capture options; vision_analyze the image and judge it as the art director).
Save often. Editor edits are in-memory until packages and levels are 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.
Report concretely. Actor labels, asset paths (/Game/...), and file locations of captures and renders.

Rules of the world while you work:

Units are centimeters; axes are Z-up, X-forward; rotations are degrees (Rotator: Roll around X, Pitch around Y, Yaw around Z). Human eye height is about 165 cm; a door is about 210×90 cm. Full tables are in references/scene-craft.md.
Content paths use long package names: /Game/Folder/Asset.Asset for project content, /Engine/BasicShapes/Cube.Cube for engine primitives.
Actor labels (what you see in the Outliner, settable, non-unique) are not actor names (internal, unique). Prefer resolving actors by label or class queries, then hold on to whatever handle the tool returns.
Prefer physically-plausible lighting values (lux, candela, Kelvin) over arbitrary brightness numbers, but first read the existing sun's intensity to learn the scene's calibration convention. Template worlds are often calibrated around intensity: 10, and physical values blow them out. references/scene-craft.md has the numbers; references/pitfalls.md #12b has the calibration rule.

From plain English to a scene

The user gives intent, not specs. Translate before you build.

Extract the brief. Subject, mood, time of day, interior or exterior, style, deliverable (screenshot? render? playable level?). Ask at most one round of clarifying questions, then commit. You are the technical director; do not bounce Unreal jargon back at the user.
Plan the build order. The order that works: level and environment shell, then blocking (major geometry and meshes in place), then lighting and atmosphere, then materials, then set dressing and detail, then camera, then capture or render. Post the plan as a todo list for multi-step builds.
Build with the loop above, one milestone at a time, screenshot at each milestone.
Art-direct yourself. Compare each screenshot against the brief: readable silhouette? believable light direction and intensity? horizon not dead-center? scale correct against a human-height reference? Fix before moving on.
Deliver. Screenshots and renders as files (MEDIA: path), plus a short summary of what exists in the level and where it was saved.

references/recipes.md has complete worked builds (exterior daylight scene, moody interior, golden-hour cinematic plus render, asset import and placement) with the exact call sequences and values.

Reference files

Load on demand; keep the SKILL.md-level rules in mind throughout.

Reference	Contents
`references/tool-surface.md`	Shipped toolsets catalog, discovery protocol detail, plugin console commands/CVars/flags, screenshot & capture paths, MCP Inspector debugging, extending with custom Python/C++ toolsets
`references/advanced-workflows.md`	Sophisticated workflows, live-verified: ProgrammaticToolset batching, Blueprint DSL authoring loop (create→DSL→compile→spawn), PIE test sessions, Sequencer orientation (140 tools), LogsToolset self-debugging, automation testing, semantic asset search, config settings, per-situation decision table
`references/scene-craft.md`	Numeric cheat sheet: physical light intensities, color temperatures, exposure/EV100, fog densities, mood recipes (noon/golden hour/overcast/night/interior), scale tables, content path conventions
`references/recipes.md`	End-to-end worked builds with exact call sequences
`references/pitfalls.md`	Setup, runtime, and workflow pitfalls with fixes, read before your first session and whenever something misbehaves

When not to use it

Two exclusions are explicit. Do not use this skill for DCC-style mesh modeling or sculpting: model in Blender and import the result. And do not use it to edit Unreal C++ project source; that is normal code work, so use the terminal. This skill is about the live editor.

Limits and gotchas

The full list lives in references/pitfalls.md. These are the ones to keep in mind from the first minute.

Start order matters. Editor and server up first, then the Hermes session. Missing mcp_unreal_engine_* tools mean the wrong order.
One call at a time. The game thread is serial; no batching, no overlap.
The editor UI freezes during each call. That is by design (game-thread execution). Warn the user during long operations and keep calls small.
Modal dialogs block everything. A tool call that opens or collides with a modal editor dialog stalls until a human dismisses it. If a call hangs indefinitely, tell the user to check the editor for a dialog.
Timeouts on long operations. Hermes' per-call default is 120 s; asset imports, big level saves, and renders can exceed it. Raise mcp_servers.unreal-engine.timeout in ~/.hermes/config.yaml for render- and import-heavy sessions.
Stale tool schemas. After authoring or hot-reloading toolsets, or enabling a plugin, run ModelContextProtocol.RefreshTools in the editor console and re-run list_toolsets. New C++ UFUNCTIONs need a full editor restart; Live Coding will not surface them.
Experimental plugin. APIs and tool shapes can change between engine versions. Trust describe_toolset over memory, including this skill's examples. When docs and the live schema disagree, the live schema wins.
Do not expose the server beyond localhost. It is loopback-only with no auth, by design. Never suggest binding it wider.
Licensing note. The server logs on start that data transmitted via the plugin to a connected LLM service is Licensed Technology under the UE EULA (§6(e)); the user is responsible for ensuring their LLM provider does not train on it. Surface this if the user asks about data handling.

A verification checklist closes the loop: list_toolsets returns toolsets at session start, scene state is queried before the first edit, changed actors and properties are re-queried and a screenshot reviewed after each milestone, levels and dirty packages are saved after each milestone and at the end, deliverables exist on disk and are reported with absolute paths, and the editor is left clean with no pending modal and no unsaved surprise.

What pairs with it

The skill leans on its own reference set: references/tool-surface.md for the toolset catalog and capture options, references/advanced-workflows.md for batching, Blueprint DSL, PIE sessions, Sequencer, and automation testing, references/scene-craft.md for numeric lighting and scale, references/recipes.md for worked builds, and references/pitfalls.md for fixes. It is the companion to the unreal-engine entry in the Hermes MCP catalog, and the vision_analyze tool is what turns a captured screenshot into an art-direction check.

Unreal MCP Skill for Hermes Agent: Drive the UE5 Editor