ChiR24/Unreal_mcp

EngineWire

EngineWire connects Claude, Cursor, VS Code or any other MCP client to a running Unreal Editor,
and let it build levels, Blueprints, UI, materials, effects and more, through a native C++ editor plugin.

_{🧭 One tool, over 400 capabilities  ·  ⚙️ Native C++ editor plugin  ·  🌐 HTTP or stdio  ·  🔐 Local and token-protected by default  ·  🎮 Unreal Engine 5.0 – 5.8}

🚀 Quick Start  ·  📖 Wiki  ·  📦 Releases  ·  💬 Discussions

📌 Which version is this? This README describes the 0.6 line: the dev branch and npm unreal-engine-mcp-server@beta. The previous stable release, 0.5.30 (npm latest), exposes 23 separate tools instead of one; see Upgrading from 0.5.x.

Contents · What it does · How it works · Quick start · The unreal tool · Configuration · Security · Engine plugins · Docker · Documentation · Development · Community

---

What it does

Nearly 400 capabilities in all, behind a single MCP tool. The assistant finds them by searching in plain words, so nobody has to learn their names. The full list is the generated Action Reference.

_{A platformer level built with the MCP, in Unreal Editor 5.8. Bottom right: the plugin's status, MCP :3000 (1), meaning the native server is running on port 3000 with one client connected.}

How it works

The EngineWire plugin runs inside the editor and does all the work, on the editor's game thread. Clients reach it in one of two ways, and both expose the same single tool, unreal:

| | 🌐 Route A · Native HTTP | 🧩 Route B · stdio | | --- | --- | --- | | Path | Client → the plugin's Streamable HTTP server at http://127.0.0.1:3000/mcp | Client → unreal-engine-mcp-server (Node.js, stdio) → the plugin's WebSocket on 127.0.0.1:8090 | | Node.js | Not needed | 20.19 or later | | Capability token | The client sends it in the X-MCP-Capability-Token header | Read from the project, given UE_PROJECT_PATH | | Best for | Claude Code, Cursor, VS Code, and several clients sharing one editor | Claude Desktop, and clients that only launch local commands |

Everything listens on 127.0.0.1 and requires the project's capability token unless you change it.

Quick start

The Quick Start page walks through this with screenshots. You need Unreal Engine 5.0 to 5.8 and a project with C++ code; a Blueprint-only project can use prebuilt binaries.

1. Add the plugin

Download EngineWire-plugin-.zip from the newest v0.6 pre-release on the Releases page, and copy the EngineWire folder it contains into your project:

MyGame/Plugins/EngineWire/

Or use a clone of this repository: copy plugins/EngineWire/, or reference the folder from your .uproject with "AdditionalPluginDirectories": ["C:/Path/To/Unreal_mcp/plugins"].

Open the project and let Unreal rebuild the plugin. When it's loaded, the status bar shows MCP off. If you see "Engine modules cannot be compiled at runtime", build the project once in Visual Studio, Rider or Xcode. More in Installation.

https://github.com/user-attachments/assets/d8b86ebc-4364-48c9-9781-de854bf3ef7d

node scripts/package-plugin.mjs "C:/Program Files/Epic Games/UE_5.7"

2. Connect your client

Route A · Native HTTP (no Node.js)

1. In Edit › Project Settings › Plugins › EngineWire, tick Enable Native MCP Server (port 3000 by default), then restart the editor. The status bar now reads MCP :3000 (0).

2. Read the capability token the plugin generated: /Saved/MCP/capability-token. Treat it like a password. 3. Add the server to your client and send the token in the X-MCP-Capability-Token header. Claude Code:

   claude mcp add --transport http unreal-engine http://127.0.0.1:3000/mcp --header "X-MCP-Capability-Token: "
   

Or in a project .mcp.json (Claude Code), reading the token from an environment variable:

   {
     "mcpServers": {
       "unreal-engine": {
         "type": "http",
         "url": "http://127.0.0.1:3000/mcp",
         "headers": { "X-MCP-Capability-Token": "${UNREAL_MCP_TOKEN}" }
       }
     }
   }
   

Cursor (.cursor/mcp.json) takes the same url and headers without type. VS Code, Windsurf and others: Connecting Clients.

4. Check it: when the client connects, the count in the status bar goes up.

{
  "mcpServers": {
    "unreal-engine": {
      "command": "npx",
      "args": ["-y", "unreal-engine-mcp-server@beta", "proxy"],
      "env": { "UE_PROJECT_PATH": "C:/Path/To/YourProject" }
    }
  }
}

Route B · stdio (Node.js 20.19+)

Add this to your client's MCP configuration, for example Claude Desktop's claude_desktop_config.json:

{
  "mcpServers": {
    "unreal-engine": {
      "command": "npx",
      "args": ["-y", "unreal-engine-mcp-server@beta"],
      "env": {
        "UE_PROJECT_PATH": "C:/Path/To/YourProject"
      }
    }
  }
}

UE_PROJECT_PATH (the project folder or its .uproject) is how the server finds the capability token and the plugin's port, so nothing else needs setting. Keep the @beta tag: without it, npm installs 0.5.30, which doesn't match a 0.6 plugin.

3. Try it

With the editor open, ask your assistant to "list the actors in the current level", "spawn a point light 300 units above the origin", or "take a screenshot of the viewport". If it doesn't connect, see Troubleshooting.

The unreal tool

Both routes expose exactly one MCP tool, unreal, with four operations. Only the contract the model is about to use gets loaded, instead of hundreds of tool schemas:

| Operation | What it does | | --- | --- | | search | Finds capabilities from 2-4 plain words, such as spawn actor or save level. Every row carries a ready-to-send nextCall. | | describe | Returns one capability's exact contract: parameters, schemas, an example, and the consent grant when one is needed | | execute | Runs one capability with validated parameters and returns the data plus a receipt of what changed | | configure | Enables or disables groups of internal tools; never touches the editor |

A typical exchange:

{ "operation": "search", "query": "spawn actor" }

{ "operation": "describe", "tool": "control_actor", "action": "spawn" }

{
  "operation": "execute",
  "tool": "control_actor",
  "action": "spawn",
  "params": { "classPath": "/Script/Engine.PointLight", "actorName": "KeyLight", "location": [0, 0, 300] }
}

• Parameters are strict. An undeclared name is refused with UNDECLARED_PARAMETER and the list of allowed names; every error carries an executable nextCall.
• Deletes need consent. 62 capabilities (all destructive ones, plus some writes) only run with the consentGrant from describe, passed back as a top-level consent field.
• Names. Both routes accept the tool + action pair; the stdio route also accepts a capability id, such as "capability": "control_actor.spawn".

Migrating from direct tool calls

The single unreal tool is permanent on both routes; there is no opt-out and no 23-tool listing to restore. A client that still calls a canonical tool name directly (tools/call with name: "manage_asset", name: "control_actor", …) receives a bounded, copy-paste-executable DIRECT_TOOL_CALL_REMOVED receipt instead of a routed call. Its nextCall drills exactly one level: { "operation": "search" } for an unknown name, { "operation": "describe", "tool": "" } when no action was given, or { "operation": "execute", "tool": "", "action": "", "params": { ... } } when the call already named an action. Run that nextCall through unreal to finish the migration. See Upgrading.

Protocol versions

Both routes negotiate the MCP protocol version at initialize. The native /mcp transport supports 2025-11-25 (latest), 2025-06-18 and 2025-03-26; the stdio server also accepts the legacy 2024-11-05 and 2024-10-07. An unsupported MCP-Protocol-Version header on the native route gets HTTP 400. Both also answer server/discover without a session, listing those versions, so a client on the newer 2026-07-28 revision falls back to initialize. Details: docs/protocol.md.

Configuration

Most setups touch one setting: Enable Native MCP Server for Route A, or UE_PROJECT_PATH for Route B. Everything is listed on the Configuration page.

Plugin settings (Project Settings › Plugins › EngineWire, saved in Config/DefaultGame.ini):

| Setting | Default | | | --- | --- | --- | | Enable Native MCP Server | off | Serve MCP over HTTP at /mcp | | Native MCP Port | 3000 | The MCP_NATIVE_PORT environment variable of the editor process overrides it | | Listen Ports | 8090,8091 | WebSocket ports for Route B | | Require Capability Token | on | Both routes refuse clients without the token | | Allow Non Loopback | off | LAN access for both listeners. See Security. |

Environment variables (Route B only, in the client's env block):

| Variable | Default | | | --- | --- | --- | | UE_PROJECT_PATH | unset | Project folder or .uproject; used to find the token and the port | | MCP_AUTOMATION_PORT | the project's first Listen Ports entry, else 8090 | Editor WebSocket port | | MCP_AUTOMATION_HOST | 127.0.0.1 | A LAN address also needs MCP_AUTOMATION_ALLOW_NON_LOOPBACK=true | | MCP_AUTOMATION_CAPABILITY_TOKEN | read from the token file | Token to present, when the server can't read the project folder | | MCP_ADDITIONAL_PATH_PREFIXES | empty | Extra content roots such as /MyPluginContent/, comma-separated; most content-path arguments also accept the mounts the connected editor reports, so this is needed only with no editor connected, for a mount the editor does not report or the server ignores, and for arguments the server treats as files (filePath, outputPath and a few others), even where outputPath names an asset | | LOG_LEVEL | info | debug, info, warn or error; logs go to stderr |

Security

• Local by default. Both routes listen on 127.0.0.1 only. LAN access needs Allow Non Loopback, and the native server refuses to bind off-loopback unless Require Capability Token is on.
• Capability token. Generated per project at /Saved/MCP/capability-token (a value typed into Capability Token overrides it) and compared in constant time. Delete the file and restart the editor to rotate it.
• Consent for destructive work. Deletes and some other writes need a per-call consent grant, which the plugin checks itself.
• Guard rails. Asset paths are limited to /Game, /Engine, /Script, /Temp, /Niagara plus configured prefixes, and a content path may also sit under a mount the connected editor reports; arguments the server treats as files (such as filePath, and outputPath even where it names an asset) never use the reported mounts; console commands that chain or quit the editor are blocked; the plugin's own settings are out of reach of automation.

Engine plugins

The bridge declares its engine-plugin dependencies, so Unreal enables them together with it.

The plugin targets every Unreal Engine minor from 5.0 to 5.8. If it fails to build on yours, please open an issue with the build log.

Docker

The image runs the stdio server. It has to reach the editor's WebSocket on 127.0.0.1, so use host networking (Linux), and pass the token because the container can't read your project folder:

docker build -t unreal-mcp .
docker run -i --rm --network host -e MCP_AUTOMATION_CAPABILITY_TOKEN= unreal-mcp

Use -i without -t: a TTY corrupts the MCP stream on stdout.

Documentation

| | | | --- | --- | | 📖 Wiki | Quick Start, Installation, Connecting Clients, Using the Gateway, Configuration, Security, Troubleshooting, FAQ, Upgrading | | 📋 [Action Reference](https://github.com/ChiR24/Unreal_mcp/blob/d