Automate Unreal Engine Editor with Hermes Agent and Unreal MCP Skill

The Unreal MCP skill connects Hermes Agent to Epic's experimental Unreal MCP plugin running inside Unreal Editor. You describe what you want in plain English, and the agent translates that into editor commands: spawning actors, adjusting lighting, framing cameras, capturing renders, and more. This guide covers setup, the discovery workflow, the operating loop, and the pitfalls you need to know before your first session.

What it does

This skill turns Hermes into a director for Unreal Editor. You can ask for single actions ("make the sun golden hour") or multi-step projects ("build a moody forest clearing with a campfire and render a shot of it"). The agent inspects the current scene, plans a build order, executes calls one at a time, and verifies results visually. You never need to touch the editor UI beyond launching it.

The skill works with any Unreal Engine 5.8+ project. It covers level building, actor manipulation, lighting and atmosphere, material instances, camera work, screenshots and renders, asset imports, scene inspection, automation tests, and general editor scripting.

Before you start

Two halves must be set up, in order: the editor side first, then the Hermes side.

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.
Edit > Plugins, enable Unreal MCP (its Toolset Registry dependency auto-enables). Restart the editor when prompted.
The typed toolsets ship separately from the server: also enable the 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.
Edit > Editor Preferences > General > Model Context Protocol, enable 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).

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 + 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 mcp_servers.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

Launch Unreal Editor, wait for the project to finish loading; confirm the server started (Output Log shows the bind address, or run ModelContextProtocol.StartServer manually).
Start the Hermes session. Tools register as mcp_unreal_engine_*. If they're missing: editor wasn't up first, start it, then open a new Hermes session.
Sanity check: call mcp_unreal_engine_list_toolsets and confirm 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 in this order:

list_toolsets → see what 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 → read 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 (new plugin enabled, toolset authored, RefreshTools run).

The alternative eager mode (Enable Tool Search off in Editor Preferences) advertises every tool as its own mcp_unreal_engine_ 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:

Inspect first. List toolsets, then query the scene/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 → 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, 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 result, next call. This overrides the general parallel-tool-calls guidance.
Read every result. Many tools (Blueprint compiles, material edits, 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).
Verify visually and structurally. After each milestone, confirm state 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).
Save often. Editor edits are in-memory until packages/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/...), file locations of captures/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 ≈ 165 cm; a door ≈ 210×90 cm. Full tables 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/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/exterior, style, deliverable (screenshot? render? playable level?). Ask at most one round of clarifying questions, then commit, you are the technical director; don't bounce Unreal jargon back at the user.
Plan the build order. The order that works: level/environment shell → blocking (major geometry/meshes in place) → lighting + atmosphere → materials → set dressing/detail → camera → capture/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/intensity? horizon not dead-center? scale correct against a human-height reference? Fix before moving on.
Deliver. Screenshots/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 + render, asset import & placement) with the exact call sequences and values.

Reference Files

Load on demand; keep 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

Pitfalls (top of mind, full list in references/pitfalls.md)

Start order matters. Editor + server up first, then the Hermes session. Missing mcp_unreal_engine_* tools = wrong order.
One call at a time. Serial game thread; no batching, no overlap.
The editor UI freezes during each call. That's by design (game-thread execution). Warn the user during long operations; 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/import-heavy sessions.
Stale tool schemas. After authoring/hot-reloading toolsets or enabling a plugin, run ModelContextProtocol.RefreshTools in the editor console and re-list_toolsets. New C++ UFUNCTIONs need a full editor restart, Live Coding won't 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.
Don't expose the server beyond localhost. Loopback-only, no auth, by design. Never suggest binding it wider.
Licensing note. The server logs on start: 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 doesn't train on it. Surface this if the user asks about data handling.

Verification Checklist

list_toolsets returns toolsets at session start (connection healthy)
Scene state queried before first edit (never assumed empty)
After each milestone: changed actors/properties re-queried and a screenshot reviewed against the brief
Level/dirty packages saved after each milestone and at the end
Deliverables exist on disk (screenshot/render paths confirmed) and are reported to the user with absolute paths
Editor left in a clean state: no pending modal, no unsaved surprise, user told exactly what was created/changed and where

When not to use it

This skill is not for DCC-style mesh modeling or sculpting. Use the blender-mcp skill for that and import the result into Unreal. It is also not for editing Unreal C++ project source code. That is normal code work and belongs in the terminal.

Limits and gotchas

The plugin is experimental. APIs and tool shapes can change between engine versions. Always trust describe_toolset over memory, including examples in this skill. When docs and the live schema disagree, the live schema wins.

The server is loopback-only with no authentication. Never expose it beyond localhost.

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.

What pairs with this

The related skill is blender-mcp for mesh modeling and sculpting. Import the result into Unreal after creating it in Blender.

Automate Unreal Engine Editor with Hermes Agent and the Unreal MCP Skill