Python Scripting with UEFN MCP

With UEFN MCP, an AI agent or another MCP client can perform tasks in the editor. When a task takes many steps, like placing hundreds of props, the agent can run them all in one Python script instead of calling a tool for each step. For large jobs, this can be many times faster.

There are two ways to run a script:

• Programmatic scripting: Safer, slower, and you can keep working in the editor while it runs.

• Execute Python: Much faster, but it has no safety checks and the editor freezes until it finishes.

Before You Begin

• Use source control, such as Lore Version Control, so you can roll back big changes.

• Set up UEFN MCP:

  • In Project Settings, enable Python Editor Scripting and UEFN MCP Toolsets. 

  • Start the UEFN MCP server and connect your AI agent or client. See the UEFN MCP page for setup.

• Ask your AI agent to list the available toolsets, and check that it can see ProgrammaticToolset and PythonScriptingTools. The tools your AI agent can use depend on the editor build and its permissions.

Choosing a Scripting Method

Choosing between programmatic scripting and Execute Python depends on your task:

Programmatic Scripting

Programmatic scripting runs a small script that can only use the editor's tools. Every change goes through a tool, so it gets the same checks and clear error messages as a normal request.

Programmatic scripts must follow these rules:

• The script can't use the unreal module. It can only import json, math, datetime, copy, re, and time. The imports go at the top of the script.

• The script must define async def run(): and return a dictionary.

• To wait, use await sleep(seconds), up to 10 seconds at a time. time.sleep doesn't work.

To get the exact rules for your editor build, call get_execution_environment first.

Example: Place 10 cubes in a row.

import json
async def run():
    for i in range(10):
        await execute_tool('EditorToolset.LevelToolset.AddToSceneFromAsset', json.dumps({
            'assetPath': '/Engine/BasicShapes/Cube.Cube',
            'name': 'Cube_%d' % i,
            'xform': {'location': {'x': i * 200.0, 'y': 0, 'z': 100.0},
                      'rotation': {'pitch': 0, 'yaw': 0, 'roll': 0},
                      'scale': {'x': 1, 'y': 1, 'z': 1}}}))
    return {'created': 10}

Execute Python

Execute Python runs your script directly in the editor with the full Unreal Python API. It’s the fastest option, and you can use it for actions without an MCP tool.

Ask the AI agent to call read_me first. It explains the rules for your session.

Execute Python has the following risks and limitations:  

• There are no safety checks. A script can change or delete anything in your project, and it can crash the editor.

• The editor freezes until the script finishes. Keep each script short, and split big jobs into several smaller scripts.

• Calls that wait or block, such as time.sleep, are rejected.

• Content made with Python isn't checked against publishing rules, so validate your project before you publish.

Example: Place the same 10 cubes.

mesh = unreal.EditorAssetLibrary.load_asset('/Engine/BasicShapes/Cube')
actors = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
for i in range(10):
    actor = actors.spawn_actor_from_object(mesh, unreal.Vector(i * 200.0, 0, 100.0))
    actor.set_actor_label('Cube_%d' % i)

Speed Comparison

Placing 1,000 cubes in a test level took the following times. Times vary by editor build, hardware, and level, so use these to compare the methods, not to predict exact times. 

Best Practices

• Check in your work before you run a script that makes a lot of changes.

• Be specific about what you want and what you don’t want. A prompt like “place 1,000 cubes” can produce a script with extra steps, such as snapping each cube to the ground, sorting the cubes into folders, or checking the results. Each extra step adds time.

• Test your script on a small batch first, like 10 cubes instead of 1,000. Mistakes are easier to spot and fix before you change your whole level.

• Only change properties you can also change in the UEFN interface. Changes to other properties fail validation, and you can’t publish your island until you fix them.

• Keep your scripts and test them again after each UEFN release.

• Validate your project often.

What to Avoid

• Don't run Execute Python scripts you don't trust; they have full access to the editor.

• Don't run a long Execute Python script while you need the editor. The editor can't respond until the script finishes.

• Don't change properties that aren't allowed in UEFN, or place content that doesn't appear in the Content Browser. It fails validation.

• Don't change content from outside your project. It can crash the editor or leave changes that aren't in your game.

Known Issues

These are known issues that we are investigating and may be resolved in a future release:

• Coordinate system conversion

  • Currently, the Python Toolsets use the XYZ format instead of the Left-Up-Forward (LUF) coordinate system. For translation between XYZ to LUF that UEFN uses, converting by hand can create errors. Execute Python provides a LUF helper function for converting coordinates, but it isn’t documented and may change between releases. If you use it, check the converted positions in your level as AI-generated conversions can still produce incorrect results.

• Hitching editor

  • MCP tool calls can cause the editor to hitch and hang.