Link an Unreal Project to Claude via MCP

Two sides, one loop. Steps 0–4 happen in the Windows Unreal editor. Steps 5–8 happen in WSL Ubuntu. The editor runs the MCP server on Windows' loopback; a local Claude client connects to it. Steps 0–8 cover the Claude Code + WSL route; an Alternative route at the end covers Claude Desktop, which skips the WSL networking entirely. Either way, this chat window can't be the client — it can't reach a server on your machine. A separate local client does the driving.

Step 0 · Windowseditor

Create or Open a Project

Plugin and server settings save per project, not globally and not per parent folder. So create or open the exact project you intend to drive, and do the plugin steps there. A Blueprint template is simplest; C++ works identically for MCP.

Note the project folder. Projects live on the D: drive, e.g. D:\mydata\Unreal_Projects\introto57.
From WSL that same folder is /mnt/d/mydata/Unreal_Projects/introto57. You'll hand this path to the setup script later.

Per-project, not cascading: enabling the plugin in one project does not affect siblings or subfolders. Each .uproject carries its own plugin state.

C: vs D: your projects live on D:, but .wslconfig always sits in the Windows user profile on C: (/mnt/c/Users/<you>/.wslconfig). The setup script reads C: for that one file and writes .mcp.json to your D: project — that split is expected.

Step 1 · Windowseditor

Enable the Unreal MCP Plugin

In the editor, open Edit › Plugins, search for Unreal MCP, and check Enabled. It automatically pulls in the Toolset Registry dependency. Restart the editor when prompted.

Step 2 · Windowseditor

Enable the AllToolsets Plugin

This is the easy step to miss. The MCP plugin exposes no tools on its own — still in Plugins, also enable AllToolsets. Without it, the server runs but your client sees zero tools. Restart again if prompted.

If your client connects but shows no tools: this step is almost always the cause. Confirm AllToolsets is enabled and the editor was restarted.

Step 3 · Windowseditor

Turn On the Server

Open Edit › Editor Preferences, find the General group, select Model Context Protocol, and turn on Auto Start Server. It binds to http://127.0.0.1:8000/mcp every time the editor launches.

# Prefer manual control instead of auto-start? Run this in the editor console (backtick key): ModelContextProtocol.StartServer

Transport note: the plugin speaks HTTP and Server-Sent Events only — no stdio, no WebSocket. That's why the WSL networking step below matters.

Step 4 · Windowseditor

Generate the Client Config (optional helper)

Unreal can write a starter .mcp.json for you. In the editor console run the command below — it drops the file into the project root and merges with any existing entry, so it's safe to run more than once.

ModelContextProtocol.GenerateClientConfig ClaudeCode

It produces exactly this:

{ "mcpServers": { "unreal-mcp": { "type": "http", "url": "http://127.0.0.1:8000/mcp" } } }

Note it writes to the Windows-side project root. For a WSL client you'll place the config on the WSL side — the setup script in Step 5 handles that for you.

Step 5 · WSLubuntu

Run the Setup Script (mirrored networking)

WSL2's 127.0.0.1 is a different loopback from Windows'. The clean fix is mirrored networking, which makes WSL share the Windows loopback so the generated config works verbatim. The setup_unreal_mcp_wsl.py script sets that up, backs up your existing .wslconfig, and writes .mcp.json into your project root.

# from your Ubuntu terminal — point --project at the /mnt/d path from Step 0 python3 setup_unreal_mcp_wsl.py \ --project "/mnt/d/mydata/Unreal_Projects/introto57"

It finds your Windows .wslconfig via /mnt/c and ensures [wsl2] networkingMode=mirrored.
It writes .mcp.json pointing at http://127.0.0.1:8000/mcp into the project root.
If mirrored networking was already on, it skips ahead and tells you to go straight to the check in Step 7.

Step 6 · WSLubuntu

Apply the Networking Change

Mirrored networking only takes effect after the WSL VM restarts. You can trigger that from Ubuntu — no PowerShell needed — because wsl.exe hands the command to the Windows host. Run:

wsl.exe --shutdown

Your terminal will drop when the VM stops. Wait about 8 seconds, then open a fresh Ubuntu window.

Run this when Ubuntu is idle. The shutdown kills all WSL-side processes. The Windows editor keeps running fine.

Step 7 · WSLubuntu

Verify the Server Is Reachable

With the editor still running (and its server auto-started), confirm the connection from Ubuntu before involving any client. Either use the script's built-in check or a raw curl:

# option A — the script's own probe python3 setup_unreal_mcp_wsl.py --check # option B — a raw request curl -i http://127.0.0.1:8000/mcp

Any response, even HTTP 400 / 405 / 406, means success — MCP endpoints commonly reject a bare GET, and that still proves reachability.
"Connection refused" means the editor or server isn't running, or mirroring didn't take. Re-check Step 3, then that the VM actually restarted.

Step 8 · WSLubuntu

Launch the Client & Test

Launch your local client from the project root — the directory that holds .mcp.json. Clients search from the launch directory upward, so starting elsewhere means it won't find the config.

cd /mnt/d/mydata/Unreal_Projects/introto57 claude

Then ask it something concrete to confirm it's seeing editor context:

# try prompts like: what actors are in my level? what are a few things you can do in Unreal?

Bypass check: to see every advertised tool directly, point the MCP Inspector at the server: npx @modelcontextprotocol/inspector over Streamable HTTP to http://127.0.0.1:8000/mcp.

Alternative route: Claude Desktop (no terminal, no WSL networking). Prefer a chat window over the terminal? Claude Desktop can host the MCP server itself and drive Unreal directly. Because Desktop runs on the Windows side — the same side as the editor — the entire WSL mirrored-networking layer (Steps 5–7) disappears. You trade it for a one-time mcp-remote bridge, since Desktop's local-server config speaks stdio while Unreal speaks Streamable HTTP. Same tools, same server, different interface.

Alt A · Windowsdesktop

Don't Use "Custom Connectors" for This

The obvious-looking path is a trap. In Desktop, Settings › Connectors › Add custom connector connects from Anthropic's cloud, not your machine — so it cannot reach a server on your own 127.0.0.1. Use the local server config instead (next step).

Why it fails: custom connectors are brokered through your Claude account over the public internet. A loopback address on your PC isn't reachable from there. This route only works for internet-hosted servers.

Alt B · Windowsdesktop

Confirm Node.js on Windows

The bridge wrapper (mcp-remote) runs via npx, which needs Node.js installed on the Windows side — not just in Ubuntu. Check from a Windows terminal (PowerShell or CMD, not WSL):

node --version

If it prints a version, you're set. If not, install Node.js on Windows first, then note the path to npx.cmd (typically C:\Program Files\nodejs\npx.cmd) for the next step.

Alt C · Windowsdesktop

Edit the Desktop Config

In Claude Desktop, open Settings › Developer › Edit Config (this opens %APPDATA%\Claude\claude_desktop_config.json). Add the unreal-mcp entry, wrapping the HTTP endpoint with mcp-remote:

{ "mcpServers": { "unreal-mcp": { "command": "C:\\Program Files\\nodejs\\npx.cmd", "args": ["mcp-remote", "http://127.0.0.1:8000/mcp"] } } }

Use the full path to npx.cmd. Desktop launches configs with a minimal PATH, so a bare npx often fails even though it works in your terminal. Point at the real npx.cmd location.

Alt D · Windowsdesktop

Fully Restart & Verify

Config changes only load on a full restart — and closing the window isn't enough. Right-click the Claude tray icon and Exit, then reopen. Make sure the Unreal editor is still running with its server on.

Verify: at the bottom of a new chat, look for the tools (hammer) icon with a count. That confirms Desktop loaded the server.
Test: ask "what actors are in my level?" — same confirmation as the Claude Code route.

What you keep, what you drop: the Windows editor steps (0–4) are identical — plugin, AllToolsets, auto-start. You skip the WSL steps (5–7) entirely. Only the client changed.

✅ You're Connected

Windows editor: plugin + AllToolsets + auto-start (shared by both routes). Then either the Claude Code + WSL path (mirrored networking, config in the project root, client launched from there) or the Claude Desktop path (mcp-remote bridge, no WSL networking). Once a tool shows up in a session, Claude can spawn actors, build and wire Blueprints, create materials and meshes, and run builds and tests — the same programmatic control you already use with the Blender bridge, aimed at Unreal.