You: "Spawn a row of glowing cubes and point a camera at them."

Agent: …calls execute_python, runs unreal API, returns the captured log.

Editor: the cubes are there.

That's the whole idea. An agent gets a small set of MCP tools wired straight into a running Unreal Editor, so natural language turns into real edits — actors, assets, materials, Blueprints — with the engine's own output flowing back so the agent can see what it did and fix its own mistakes.

Making games is hard, and the learning curve keeps a lot of good ideas trapped in people's heads. UnrealMCP is a bet that the gap between "I can picture it" and "it exists in the engine" should be a conversation. It's also a great way to learn Unreal — you can watch the agent work and read every API call it makes.

┌─────────────┐   MCP / stdio   ┌───────────────────┐   TCP :55557   ┌─────────────────────┐
│  Claude /   │ ──────────────► │  Python MCP server │ ─────────────► │  UnrealMCP plugin    │
│  Cursor /   │                 │     (server/)      │                │  (in Unreal Editor)  │
│  Copilot    │ ◄────────────── │                    │ ◄───────────── │  runs on game thread │
└─────────────┘    tool calls   └───────────────────┘   JSON cmds     └─────────────────────┘

• Plugin (MCPProject/Plugins/UnrealMCP) — a UEditorSubsystem starts a TCP server on 127.0.0.1:55557 from an FRunnable worker thread. Requests are JSON { "type": <command>, "params": {…} }; each command is marshalled onto the game thread and answered with { "status": "success" | "error", … }.
• Server (server/) — a FastMCP server (stdio transport) exposing MCP tools that forward to the plugin.

The headliner tool, execute_python, runs code in the editor's Python scope (the full unreal module) and returns captured logs and any exception trace — so the agent always knows what actually happened. It's the universal escape hatch while higher-level tools grow up around it.

The actor tools are thin wrappers over execute_python — no plugin rebuild needed to add more, so the surface grows fast.

Requirements: Unreal Engine 5.7 (other 5.x likely work with minor tweaks), a C++ toolchain UnrealBuildTool can use (Visual Studio 2022 or VS Build Tools 2022 with the MSVC v143 toolchain + a Windows 10/11 SDK), Python 3.10+, and an MCP-capable client (Claude Desktop / Claude Code, Cursor, …).

1 — Build the plugin

& "C:\Program Files\Epic Games\UE_5.7\Engine\Build\BatchFiles\Build.bat" `
  MCPProjectEditor Win64 Development `
  -Project="<repo>\MCPProject\MCPProject.uproject" -WaitMutex

Open MCPProject/MCPProject.uproject. The plugin auto-starts its server on load — look for MCP server listening on 127.0.0.1:55557 in the Output Log.

2 — Set up the MCP server

cd server
python -m venv .venv
.venv/Scripts/python -m pip install -r requirements.txt   # Windows

3 — Connect your agent

See docs/connecting-agents.md for Claude Desktop / Claude Code / Cursor. Minimal Claude Desktop entry:

{
  "mcpServers": {
    "unreal-mcp": {
      "command": "<repo>/server/.venv/Scripts/python.exe",
      "args": ["<repo>/server/unreal_mcp_server.py"]
    }
  }
}

With the editor open and the agent connected, ask:

"Use the unreal-mcp ping tool." → returns pong.

"Spawn a cube at the origin." → the agent calls execute_python:

import unreal
sub = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
sub.spawn_actor_from_class(unreal.StaticMeshActor, unreal.Vector(0, 0, 0))

No agent handy? Run the bundled round-trip smoke test (editor open):

cd server && .venv/Scripts/python test_roundtrip.py

• End-to-end pipeline: ping + execute_python with log/error feedback
• Actor commands — spawn_actor / list_actors / set_actor_transform / delete_actor
• More native coverage — assets, materials, Blueprints, Niagara…
• Blueprint graph authoring (K2Node creation + pin wiring)
• A real grounding loop — viewport screenshots + structured error feedback
• Packaging / runtime agent support

See the Releases for what's shipped.

UnrealMCP lets an agent run arbitrary Python inside your editor. The bridge binds to loopback only and runs only while the editor is open — but there's no auth on the local socket yet. Read SECURITY.md before you wire up anything you don't fully trust.

This is young and there's a lot of surface to cover — new commands, docs, bug reports, or just trying it and telling us what broke. Start with CONTRIBUTING.md; agents and humans alike should skim AGENTS.md for how the bridge is built.

MIT © x0cipher