dcc-mcp-unreal

<p align="center"> <img src="docs/assets/dcc-mcp-unreal.svg" alt="DCC-MCP · UNREAL" width="600"> </p> <!-- Badges -->

Open-source Unreal Engine adapter for the DCC Model Context Protocol (MCP) ecosystem. It connects Unreal through an embedded Python server or a native standalone sidecar, both built on dcc-mcp-core.

MCP-compatible agents (Claude Desktop, Cursor, OpenClaw, …) can use typed tools to inspect scenes, author assets and Blueprints, control cinematics and effects, and validate results through PIE and Unreal Automation.

<!-- dcc-mcp-agent-quickstart:start -->

Use Unreal Engine with AI agents

Install the official DCC-MCP Agent Skill. Codex users can use the native plugin marketplace:

codex plugin marketplace add dcc-mcp/dcc-mcp-agent-plugins
codex plugin add dcc-mcp@dcc-mcp

For Claude Code, CodeBuddy, Cursor, Gemini CLI, and other supported agents, use the official installation guide. Start Unreal Engine, enable this adapter, and verify that the running instance is registered:

dcc-mcp-cli list

Then ask your agent:

Use dcc-mcp to inspect the current Unreal Engine project and level.

The list must include dcc_type=unreal. If it does not, follow the connection troubleshooting guide.

<!-- dcc-mcp-agent-quickstart:end --> <!-- dcc-mcp-coverage-pointer:start --> <!-- Generated from dcc-mcp-catalog.yml by scripts/generate_adapter_pointer.py in dcc-mcp/dcc-mcp-core. Do not edit by hand. -->

Part of the DCC-MCP host matrix

dcc-mcp-unreal — Unreal Engine plugin and adapter for DCC-MCP.

It is one of 48 host adapters in the DCC-MCP catalog. Every adapter speaks the same MCP protocol and builds on the same core runtime contract; each one exposes the tools its own host needs on top of that.

• All host adapters and install metadata
• Host matrix on the core README
• Showcase

This block is generated from the catalog entry in dcc-mcp-catalog.yml. Re-run the generator after changing the catalog.

<!-- dcc-mcp-coverage-pointer:end -->

Agent workflow

AI agents should use the shared gateway through dcc-mcp-cli; IDE users may continue to use the MCP endpoint. Prefer typed skills and tools over raw scripts.

Install or update the CLI

dcc-mcp-cli is the preferred control path for every shell-capable agent. If it is missing, ask the user before installing the latest official release:

# Linux/macOS
curl -fsSL https://raw.githubusercontent.com/dcc-mcp/dcc-mcp-core/main/scripts/install-cli.sh | sh

# Windows PowerShell
powershell -ExecutionPolicy Bypass -c "irm https://raw.githubusercontent.com/dcc-mcp/dcc-mcp-core/main/scripts/install-cli.ps1 | iex"

Keep an official build current through the release manifest:

dcc-mcp-cli update check
dcc-mcp-cli update apply

update apply downloads and stages the latest CLI for the next launch. It does not update a running dcc-mcp-server; update that server in its own environment.

dcc-mcp-cli dcc-types
dcc-mcp-cli list
dcc-mcp-cli search --query "<task>" --dcc-type unreal
dcc-mcp-cli describe <tool-slug>
dcc-mcp-cli call <tool-slug> --json '{"key":"value"}'

dcc-types reports release-catalog support; list reports live sessions. If a tool belongs to an inactive progressive skill, call dcc-mcp-cli load-skill <skill-name> --dcc-type unreal before retrying. For post-task improvement, attach a stable session id with --meta-json, query dcc-mcp-cli stats --range 24h --session-id <task-id>, then pass the bounded evidence to the review_skill_improvement prompt from dcc-mcp-skills-creator.

---

Overview

dcc-mcp-unreal follows the same architecture as dcc-mcp-maya:

Agent (Claude / Cursor)
    │  dcc-mcp-cli or MCP
    ▼
Shared gateway  →  Unreal MCP instance  ←  SkillCatalog
    │
    ▼
Embedded Python | native sidecar | optional Epic MCP bridge
    │
    ▼
Unreal main thread  →  Unreal Editor API / Toolset Registry

Each skill script is a standalone Python file that uses Unreal Engine's unreal Python module. Scripts are discovered from SKILL.md plus sibling tools.yaml metadata and exposed as MCP tools automatically.

---

Why DCC MCP when Unreal already has an official MCP?

MCP is a protocol, not a complete automation product. It standardizes how an AI client discovers context and invokes tools; it does not decide which editor operations exist, how extensions are packaged, how multiple DCC instances are discovered, or how tools are routed and operated safely. This separation is a core part of MCP's extensible architecture.

Epic's Unreal MCP is valuable: it is an engine-native, experimental MCP server in Unreal Engine 5.8+, and its Toolset Registry lets teams add Python and C++ tools. DCC MCP is not a competing wire protocol or a fork of that server. It is the broader, open-source control and extension layer around Unreal and the rest of a DCC pipeline.

| Capability | Epic Unreal MCP | DCC MCP Unreal | | --- | --- | --- | | Primary role | Expose one Unreal instance through MCP | Discover, extend, and operate Unreal through the shared DCC MCP ecosystem | | Engine coverage | Experimental in Unreal Engine 5.8+ | Capability-gated support from Unreal Engine 4.18+, including Python and standalone sidecar paths | | Extension model | Unreal Toolset Registry with Python or C++ toolsets | Portable SKILL.md + tools.yaml packages, built-in and external skill paths, plus the Epic Toolset Registry bridge | | Discovery and routing | Clients connect to the editor's local endpoint | Progressive search/load/call, stable gateway routing, CLI access, and multiple live-instance discovery | | Execution contract | Unreal-native tool schemas and game-thread execution | Typed schemas plus affinity, timeout, read-only, destructive, and idempotency metadata | | Pipeline scope | Unreal Engine | The same gateway and skill contract across Unreal and other DCC adapters |

On Unreal Engine 5.8+, DCC MCP can discover and call the installed Epic endpoint through the unreal-official-mcp skill while preserving Epic's tool names and schemas. It does not copy or redistribute Epic's NoRedist plugin. The resulting capability set is therefore:

DCC MCP native skills + optional Epic toolsets + shared gateway/CLI + cross-DCC integrations.

That is why DCC MCP has a larger system-level capability surface. "Larger" does not mean every DCC MCP tool is better than its engine-native equivalent; it means you keep the official tools where they are strongest and gain the version reach, extension packaging, routing, and pipeline composition around them.

---

Features

• Skills-First workflow — drop a SKILL.md + scripts/ directory anywhere and it becomes MCP tools automatically
• Zero boilerplate — use @skill_entry, unreal_success(), unreal_error() helpers identical in spirit to dcc-mcp-maya's @with_maya, maya_success()
• Broad typed coverage — actors, assets, Blueprints, levels, materials, cinematics, Niagara, MetaSound, Chaos, Fab, PIE, automation, and packaging
• Cross-version runtime — embedded Python where available and a native standalone sidecar for legacy or Pythonless engines
• Progressive discovery — search, load, and call only the skills needed for the task through the shared gateway and CLI
• Contract-aware execution — schemas declare thread affinity, timeouts, mutability, destructiveness, and idempotency
• Official MCP composition — bridge installed UE 5.8+ Epic toolsets without copying or redistributing Epic's plugin

---

Requirements

| Requirement | Version | |-------------|---------| | Unreal Engine | 4.18+ (capability-gated) | | Unreal Python Editor Script Plugin | optional; required for in-editor Python skills | | Python | 3.9+ for Python skills; optional for the native sidecar path | | dcc-mcp-core | >= 0.20.13, < 0.21.0 |

See the Unreal version compatibility contract for native-only, Python-enabled, and UE 5.8 official-MCP integration tiers.

Enable the Python Plugin

1. Open your Unreal Engine project
2. Edit → Plugins → search "Python"
3. Enable "Python Editor Script Plugin"
4. Restart the editor

---

Installation

📖 Agent-first install, verify, upgrade, and uninstall — the standard lifecycle contract. The extended installation guide covers pip install, uplugin deployment, GitHub Releases, UE 4.18–5.8+ matrix, agent-oriented paths, environment variables, and troubleshooting.

Quick Install

No system Python (Windows native sidecar):

Invoke-WebRequest https://raw.githubusercontent.com/dcc-mcp/dcc-mcp-unreal/v0.3.0/scripts/install-standalone.ps1 -OutFile install-standalone.ps1
.\install-standalone.ps1 -Version v0.3.0

For Python-enabled engines, pick the one-liner for your engine version:

# UE 5.5 / 5.4 / 5.3 (Python 3.11)
& "C:\Program Files\Epic Games\UE_5.5\Engine\Binaries\ThirdParty\Python3\Win64\python.exe" -m pip install dcc-mcp-unreal

# UE versions whose embedded Python is older than 3.9 use the standalone
# sidecar command above instead of pip installation.

Enable the Python Editor Script Plugin in Unreal Editor (Edit → Plugins → "Python"), restart, and you're ready.

Uplugin (from GitHub Releases)

Download the matching DccMcpUnreal-<version>-ue<engine>-win64.zip from Releases, extract it into <project>/Plugins/DccMcpUnreal/, and enable the plugin in Unreal Editor.

Development Install

git clone https://github.com/dcc-mcp/dcc-mcp-unreal
cd dcc-mcp-unreal
pip install -e ".[dev]"

Build Plugin Package

$env:UE_ROOT = "C:\Program Files\Epic Games\UE_5.7"
vx just package          # Output: dist/DccMcpUnreal/
vx just deploy "C:\Path\To\MyUnrealProject"

See the installation guide for build-from-source, UE version matrix, and agent-oriented automation paths.

---

Quick Start

Open Unreal Engine's Output Log → Python console (or use the Python Script Plugin terminal):

import dcc_mcp_unreal

# Start on an OS-assigned instance port
handle = dcc_mcp_unreal.start_server()
print(handle.mcp_url())

# Connect your MCP agent to the URL above.
# When done:
handle.shutdown()

Agents normally connect to the stable gateway at http://127.0.0.1:9765/mcp. Use dcc-mcp-cli list when a direct instance URL is needed.

Representative built-in tools

| Tool name | Description | |-----------|-------------| | unreal_actors__list_actors | List all actors in the current level | | unreal_actors__spawn_actor | Spawn an actor by class at a world position | | unreal_automation__mcp_self_check | Validate the active MCP server without restarting it | | unreal_automation__list_automation_tests | List native Unreal Automation tests | | unreal_automation__queue_automation_tests | Queue native Unreal Automation tests from MCP | | `unreal_fab_assets__prepare_free_ass