ossrules.md

unreal-mcp

Automate Unreal Engine editor scenes, actors, and renders.

  • unreal
  • unreal-engine
  • ue5
  • 3d
  • mcp
  • scenes
  • cinematics
  • lighting
  • gamedev

Declared platforms: linux · macos · windows

Install
npx skills add 'https://github.com/NousResearch/hermes-agent/tree/main/optional-skills/creative/unreal-mcp'
Download bundle ↓
main · 24fd22b ↗Scanned 2026-09-15

Contributors

GitHub-linked commit authors for this SKILL.md at the saved revision. Co-authors and history before file renames are not included.

File history ↗

SKILL.md

SKILL.mdBrowse 6 files
View on GitHub
3,254 tokens

13,893 bytes
Token encoding: o200k_base
Snapshot 24fd22b

---name: unreal-mcpdescription: Automate Unreal Engine editor scenes, actors, and renders.version: 1.0.0requires: Unreal Editor 5.8+ with the Unreal MCP plugin enabled and its server runningauthor: Hermes Agentlicense: MITtags: [unreal, unreal-engine, ue5, 3d, mcp, scenes, cinematics, lighting, gamedev]platforms: [linux, macos, windows]metadata:  hermes:    tags: [unreal, unreal-engine, ue5, 3d, mcp, scenes, cinematics, lighting, gamedev]    related_skills: []--- # Unreal Engine MCP Skill Companion skill for the `unreal-engine` entry in the Hermes MCP catalog. TheMCP server (Epic's official, experimental "Unreal MCP" plugin, internal id`ModelContextProtocol`) runs INSIDE the Unreal Editor process and exposeseditor functionality as typed tools. This skill teaches how to drive it well:discovering the live tool surface, sequencing calls safely, translatingplain-English asks into scenes that actually look good, and verifying workvisually. 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 alevel, spawn/move/delete actors, set up lighting and atmosphere, create ortune material instances, frame a camera shot, capture screenshots or renders,import assets, inspect the scene or UI, run automation tests, or script theeditor. Works for single actions ("make the sun golden hour") and forcomplete multi-step projects ("build me a moody forest clearing with acampfire and render a shot of it"). Don't use for: DCC-style mesh modeling/sculpting (model in Blender andimport the result), or for editing Unreal C++ project source (that's normalcode 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 1. Unreal Editor **5.8+** with a project open. (macOS: full Xcode must be   installed and its license accepted — the editor exits on first launch   without it; see pitfalls.)2. **Edit > Plugins** — enable **Unreal MCP** (its Toolset Registry   dependency auto-enables). Restart the editor when prompted.3. 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.4. **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 itwhile the editor + server are up so the probe sees the real surface. If theuser 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 — thatwrites `.mcp.json`-style files for Claude Code/Cursor/etc. Hermes connectsfrom `config.yaml` via the catalog entry. ### Every session 1. 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).2. 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.3. 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 onlythree meta-tools, and every real tool is reached through them. Through Hermesthey 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: 1. `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`.2. `describe_toolset` on the group you need → read the real parameter   schemas. Never guess parameter names — schemas are the contract.3. `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 sidechanges (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_<tool>` entry. Discoverythen happens at `hermes mcp install`/`configure` time instead. Tool-searchmode is the default and what this skill assumes; it also keeps schema tokensout of every API call, so prefer it. See `references/tool-surface.md` for the shipped toolset catalog, authoringcustom toolsets, and the full plugin configuration/console-command reference. ## Operating Loop Every Unreal task follows the same loop: 1. **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.2. **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`).3. **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.4. **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).5. **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).6. **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.7. **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: 1. **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.2. **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.3. **Build with the loop above**, one milestone at a time, screenshot at   each milestone.4. **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.5. **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++ `UFUNCTION`s 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
Discovery context

Discovered by repository scan. No exact path reference found in the snapshot’s root AGENTS.md.

← All Hermes Agent skillsProject instructions →