Claude Code Unreal Engine Plugin: Setup Guide

A post about Epic Games’ Claude Code plugin for Unreal Engine took off on X this weekend, and a lot of the replies ask the same thing: how does it actually connect? The plugin itself has been in Anthropic’s official marketplace since late June, but setup is split between two places, Epic’s Unreal MCP docs and the plugin’s GitHub README. This guide puts them in one order and points out the parts that trip people up.

How the pieces fit

There are two separate things here, and mixing them up causes most of the confusion.

Unreal MCP is an engine plugin (identifier ModelContextProtocol) that runs an MCP server inside the Unreal Editor process. It listens on http://127.0.0.1:8000/mcp by default. Epic marks it Experimental in the UE 5.8 docs, and warns that APIs and data formats can change.

The Claude Code plugin (unreal-engine-skills-for-claude-code) doesn’t contain the server. It adds an unreal-mcp skill that teaches Claude how to drive the editor, plus a SessionStart hook that tells Claude it’s in an Unreal project so it defaults to UE conventions like UObject patterns, Slate, and UHT.

So the flow is: the editor hosts the tools, .mcp.json tells Claude Code where they are, and the plugin tells Claude how to use them. If MCP itself is new to you, Part 4 of the Mastering series covers the basics.

Step 1: Enable the plugins in Unreal

In Unreal Editor, open Edit > Plugins and enable two plugins:

• Unreal MCP (the server and transport)
• All Toolsets (the actual tools)

Restart when prompted. Both depend on the Toolset Registry plugin, which turns on automatically.

Don’t skip All Toolsets. The plugin’s setup reference is blunt about it: with only ModelContextProtocol enabled, the server starts but exposes no tools. All Toolsets is off by default. If you’d rather expose a smaller surface, enable individual toolset plugins instead.

You can also do this in the .uproject file by adding both entries to the Plugins array:

{ "Name": "ModelContextProtocol", "Enabled": true },
{ "Name": "AllToolsets", "Enabled": true }

Step 2: Start the MCP server

The server is stopped by default. For a one-off session, open the editor console (backtick key) and run:

ModelContextProtocol.StartServer

Pass a port if 8000 is taken, for example ModelContextProtocol.StartServer 8123.

To start it on every launch, go to Edit > Editor Preferences > General > Model Context Protocol and turn on Auto Start Server. The same panel holds the port and URL path. The setting is stored per user in Saved/Config/<Platform>Editor/EditorPerProjectUserSettings.ini, so it isn’t committed to source control.

Check the Output Log after it starts. A failure to bind, such as a port conflict, shows up there under LogModelContextProtocol.

Step 3: Generate .mcp.json

The editor doesn’t write a client config on its own, and the Claude Code plugin doesn’t ship one either. With the server running, run this in the editor console:

ModelContextProtocol.GenerateClientConfig ClaudeCode

It writes .mcp.json with an unreal-mcp entry pointing at the running server:

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

Where it lands depends on your build. In an installed (launcher) build, it goes next to the .uproject. In a source build, it goes in the workspace root next to Engine/, not next to the .uproject. That matters, because Claude Code reads .mcp.json from the folder you start it in. Re-run the command after changing the port or path; it merges into the existing file.

All instead of ClaudeCode writes configs for Cursor, VS Code, Gemini, and Codex too. Codex is the odd one: its TOML config is write-once, so a stale .codex/config.toml has to be removed or edited by hand.

Step 4: Install the Claude Code plugin

Start Claude Code from the folder that holds .mcp.json, then run:

/plugin install unreal-engine-skills-for-claude-code@claude-plugins-official

Per the Claude Code plugin docs, this opens the /plugin panel on the plugin’s details so you can review it and pick a scope, rather than installing silently. Claude Code registers the official marketplace the first time you open an interactive session. If it’s missing, add it with /plugin marketplace add anthropics/claude-plugins-official.

Scope decides who gets it:

For a team, Epic’s README suggests committing this to .claude/settings.json:

{
  "enabledPlugins": {
    "unreal-engine-skills-for-claude-code@claude-plugins-official": true
  }
}

The Claude Code docs add one caveat: committing the entry turns the plugin on for collaborators but doesn’t download it, so each person may still need to run claude plugin install unreal-engine-skills-for-claude-code@claude-plugins-official --scope project once.

On Windows, run Claude Code under Git Bash or WSL. The SessionStart hook is a bash script, and native PowerShell without bash on PATH skips it. The MCP tools still work without it.

Step 5: Verify the connection

Epic’s README lists a short check:

1. Run /plugin and confirm the Installed tab shows the plugin as enabled. That proves the skill and hook loaded, nothing more.
2. Run /mcp and look for unreal-mcp as connected.
3. Ask something read-only, like “List all actors in the current level” or “What actors do I have selected?”

If step 3 works, you’re done. If Claude Code can’t find the server, the Epic docs suggest launching the editor first, then starting Claude Code in the folder where .mcp.json was written.

Why Claude sees only three tools

When you open /mcp, you won’t see hundreds of Unreal tools listed. Tool search is on by default, so the server advertises three meta-tools: list_toolsets, describe_toolset, and call_tool. Claude lists toolsets, reads the schema for the one it needs, then dispatches the real tool through call_tool on the same turn.

According to the README, this keeps the context window small and the prompt cache warm, since the tool list never changes mid-session. How Claude Code connects to MCP servers in general is covered in Deep Dive 10: Worktrees & MCP. You can turn it off with bEnableToolSearch=False, but you’ll pay for a much larger schema payload.

The tools cover a lot of the editor: actors and components, Blueprints (graphs, nodes, pins, variables, compile), materials, meshes, Control Rigs, Sequencer, Niagara, UMG widgets, gameplay tags and GAS, and C++ automation tests. There’s also a scripting toolset that batches several calls into one Python script.

Read the security section before you prompt

Epic’s README has a security section that’s easy to scroll past. The short version:

• Localhost isn’t a trust boundary. The server checks origins, which stops a browser tab from talking to it, but any process running as your user on the same machine can connect. There’s no authentication layer. Don’t run it on shared machines or expose the port.
• execute_tool_script runs arbitrary Python inside the editor, with access to the project on disk and every toolset API.
• Avoid --dangerously-skip-permissions with this plugin loaded. Without the per-tool approval gate, a bad prompt can change a lot of project state before you notice. Claude Code’s permission model is explained in Deep Dive 5.
• Commit before long sessions. MCP tools edit live UObject state and can move or delete tracked assets in one call. Not every edit is undoable, especially across compiles.

The skill itself tells Claude to save before and after bulk changes, wait for compilation to finish, serialize calls that touch the same asset, and stop Play-in-Editor if results look wrong. Those are good rules to follow yourself when you review what it did.

Troubleshooting

For lower-level debugging, Epic suggests pointing the MCP Inspector (npx @modelcontextprotocol/inspector) at http://127.0.0.1:8000/mcp over Streamable HTTP. It lists every tool with its schema and lets you call them without an agent in the middle.

Going further: project skills and custom toolsets

Two features stand out for anyone with a real project. First, a project can register its own Agent Skills, reached through AgentSkillToolset, for naming conventions, folder layout, or a studio’s way of doing a multi-step task. The unreal-mcp skill tells Claude to check for them and follow them over its defaults. That’s the same pattern as Claude Code skills, covered in Part 3: Skills & Subagents.

Second, you can write your own tools. A toolset is a Python class deriving from unreal.ToolsetDefinition (or UToolsetDefinition in C++), and the plugin includes a create-toolset skill to scaffold one. Run ModelContextProtocol.RefreshTools after adding it. New C++ UFUNCTION tools need a full editor restart, since Live Coding doesn’t pick up new declarations.

Not making games? The same setup pattern (a local MCP server, a generated .mcp.json, a plugin with a skill on top) is turning up in more desktop tools. We build small iOS apps at ZenoLab, which you can browse in the app catalog, and the workflow posts in this blog apply there too.

Sources

• Unreal MCP docs (UE 5.8): dev.epicgames.com
• Plugin repo and README: EpicGames/unreal-engine-skills-for-claude-code-plugin
• Setup reference: setup.md
• Operations and troubleshooting: operations.md
• Marketplace listing: claude.com/plugins
• Marketplace PR: anthropics/claude-plugins-official#3396
• Installing plugins: code.claude.com/docs/en/discover-plugins