UE5 MCP

An Unreal Engine 5 editor plugin and a Python MCP server that let AI agents build and inspect Unreal projects: Blueprints, assets, levels, animation, AI, audio, VFX, cinematics, playtesting, and packaging.

MCP client  --streamable HTTP-->  Python server (FastMCP)  --REST-->  UE5_MCP plugin  -->  Unreal Editor
            http://localhost:9000/mcp                     http://localhost:<api port>

Requirements

• Unreal Engine 5.7. The editor target is built and tested on 5.7.1.
• A toolchain that can compile editor plugins, because the plugin ships as source. Development and testing happen on Windows, and the commands below use Windows paths.
• Python 3.10 to 3.13. Python 3.14 is excluded by pyproject.toml because the MCP dependency may not support it yet.

The engine plugins this one depends on, such as Niagara, PCG, StateTree, and GameplayAbilities, are listed in UE5_MCP.uplugin and enabled with it.

Installation

For the full guide, including client setup and troubleshooting, see INSTALL.md. AI agents can follow AGENT_INSTALL.md.

1. Clone the repository into your project's Plugins folder:

   cd <YourUEProject>/Plugins
   git clone https://github.com/cutehusky/ue5-mcp.git UE5_MCP
   

2. Open the project, let Unreal build the plugin, and check that UE5_MCP is enabled in the Plugins tab.

3. Install the MCP server:

   cd UE5_MCP/Python/MCP
   python -m venv .venv
   .venv/Scripts/python -m pip install --upgrade pip
   .venv/Scripts/python -m pip install -e .
   

   Run directly, mcp_server.py also sets itself up. It reuses .venv or .venv-ue311 if either works, otherwise creates .venv, then re-launches inside it and installs any missing httpx, mcp, and python-dotenv packages.

   Variable	Effect
   UE5_MCP_VENV	Use this virtual environment directory instead
   UE5_MCP_AUTO_INSTALL=0	Do not install missing packages

Usage

Start from the editor

1. Open Window > UE5_MCP.
2. Set the Python executable (for example <project>/Plugins/UE5_MCP/Python/MCP/.venv/Scripts/python.exe), the path to mcp_server.py, and the MCP port.
3. Click Run Python MCP server. This also starts the Unreal API server if needed and passes both ports to Python, so no .env file is required.

To pick the Unreal API port yourself, turn off Use automatic port allocation. The Python process stops when the plugin shuts down.

Start from a terminal

Start the Unreal API server from the tab first, then run:

.venv/Scripts/python mcp_server.py --port 9000 --ue-api-url http://localhost:8080

Instead of passing flags, you can set the values in Python/MCP/.env. Flags take priority. The defaults are port 9000 and http://localhost:8080.

PORT=9000
UE5_REST_API_URL=http://localhost:8080

Connect a client

Point any MCP client that supports streamable HTTP at http://localhost:9000/mcp, using your MCP port.

Scripting from Python

Scripts can call any tool directly with from ue5_client import ue. See the ue5-python-scripting skill and FEATURE_MAP.md.

Finding tools

The server has 1,732 tools, and listing them all costs about 440k tokens. By default, clients see 144: a core game-making set of 141 plus these three catalog tools, which reach everything else.

TOOLS.md lists every tool by feature. Start the server with --all-tools to list everything. To change the core set, edit CORE_TOOLS in Python/MCP/ue5_tools/catalog.py.

Some tools cover several related operations or value types, and take a required variant argument. For example, set_light takes variant="scalar" or variant="bool". Each tool's description lists what every variant requires and accepts. Older tool names are mapped to these in IMPLEMENTED_FEATURES.md, under "Merged tools".

Calling tools

Mutation tools use the asset or Blueprint path first, followed by the operation-specific values. Optional values are omitted or use documented defaults.

Examples:

create_blueprint("/Game/UE5MCP/TestBP", "/Script/Engine.Actor")
create_widget_blueprint("/Game/UE5MCP/TestWidget")
validate_asset("/Game/UE5MCP/TestBP.TestBP", asset_class="Blueprint")
edit_animation_data(variant="edit_animation_curve", asset_path="/Game/Anim.Run.Run", operation="add_sync_marker", curve_name="Foot_L", notify_track="Sync")
create_material_expression("/Game/Materials/M_MCP.M_MCP", "/Script/Engine.MaterialExpressionScalarParameter", expression_name="Speed")

DELETE operations that carry JSON bodies are sent with an explicit HTTP DELETE request. Python/MCP/tests/smoke_bug_report_regression_live.py keeps these fixes covered.

Valid class names, Blueprint paths, and signature formats are in common_instruction in Python/MCP/ue5_tools/app.py.

Coverage

Implementation status

Reviewed 2026-11-04 against the UE 5.7 source routes and Python tools. A tool existing does not mean it has been verified: see UNTESTED_FEATURES.md. IMPLEMENTATION_PLAN.md is the authoritative list of what is still to do.

Important limitations

• /assets/batch accepts an ordered Operations array and preserves the legacy single-operation body. It is non-atomic: earlier successful operations remain applied after a later failure. Batch preflight rejects nested object-reference traversal.
• Remaining Control Rig channel/space options and other Sequencer track combinations remain open. The frame evaluator samples transform, visibility, and float-property tracks together in preview or direct mode, restoring actor values and map package dirty state. Class-only spawnable templates also survive save and editor restart.
• Some new asset routes expose reflected-property editing rather than dedicated typed DTOs.
• The property system uses UE 5.7 FProperty::ImportText_Direct and native export logic. Nested object paths require an existing object; array indexes must already exist.
• Python syntax validation and the UE 5.7 DemoForPluginEditor Development build pass, including UE5_MCP.
• UE documentation results are based on classes currently loaded in the running editor; unloaded engine/plugin classes are not returned until their modules/assets are loaded.
• Live actor routes operate on the current editor world. Actor deletion and asset-editor closing require bConfirm=true; viewport writes require an active level viewport.
• load_editor_world refuses to switch maps during PIE. Its dirty_policy is fail, save, or discard; the default reports separate dirty map/content package lists without changing state, while discard additionally requires confirm=True.

Testing

The scripts are in Python/MCP/tests/. The smoke_*_live.py scripts need a running editor, and some expect the plugin at <project>/Plugins/UE5_MCP.

For unattended runs, launch the editor with -UE5MCPApiPort=8080. This starts only the Unreal API on that port. Without the flag, startup is controlled from the tab.

Run these from the plugin directory:

python Python/MCP/tests/smoke_sequencer_live.py

This one exercises Sequencer authoring against a disposable, unsaved sequence, using the running editor.

python Python/MCP/tests/smoke_sequencer_persistence.py

This one needs port 8080 free. It starts two command-line editor sessions to verify save and reload, then deletes its uniquely named test sequence.

Roadmap

Next, from IMPLEMENTATION_PLAN.md:

1. Add Blueprint debugging and C++ feedback: breakpoints, C++ class creation, compile and Live Coding status.
2. Build one small game using only the core tools, then correct CORE_TOOLS based on what was missing.
3. Remove the duplicate start_play_in_editor and stop_play_in_editor tools, and try the tool list in a real client such as Claude Desktop or Cursor.

Documentation

Contributing

Tools live in Python/MCP/ue5_tools/, one module per feature group, and mcp_server.py loads them automatically. Keep them aligned with the plural REST routes, such as /blueprints/functions.

For new work:

• Follow the common API contract in IMPLEMENTED_FEATURES.md: dry run, confirmation, transactions, and saving only on request.
• Record each new feature in IMPLEMENTED_FEATURES.md and UNTESTED_FEATURES.md, then remove it from IMPLEMENTATION_PLAN.md.
• Report unsupported optional engine plugins as unavailable, never as implemented.

License

MIT