unreal-mcp

Name: unreal-mcp
Author: runreal

@runreal

Repository

About unreal-mcp

MCP server for Unreal Engine that uses Unreal Python Remote Execution

#python #typescript #mcp #unreal #unreal-engine #modelcontextprotocol

Basic information

Config

Add this server to your MCP-compatible client using the configuration below.

{
  "mcpServers": {
    "unreal": {
      "command": "npx",
      "args": [
        "-y",
        "@runreal/unreal-mcp"
      ]
    }
  }
}

Tools

Set the Unreal Engine path

Set the Project path

Get the current Unreal Engine path

Get the current Unreal Project path

Execute any python within the Unreal Editor. All python must have `import unreal` at the top. CHECK THE UNREAL PYTHON DOCUMENTATION BEFORE USING THIS TOOL. NEVER EVER ADD COMMENTS

List all Unreal assets Example output: [''/Game/Characters/Hero/BP_Hero'', ''/Game/Maps/TestMap'', ''/Game/Materials/M_Basic''] Returns a Python list of asset paths.

Export an Unreal asset to text Example output: Binary data of the exported asset file Returns the raw binary content of the exported asset.

Get information about an asset, including LOD levels for StaticMesh and SkeletalMesh assets Example output: [{'name': 'SM_Cube', 'is_valid': True, 'is_u_asset': True, 'is_asset_loaded': True, 'class': 'StaticMesh', 'path': '/Game/Meshes/SM_Cube', 'package': 'SM_Cube', 'package_path': '/Game/Meshes/SM_Cube', 'lod_levels': [{'lod_index': 0, 'num_vertices': 24, 'num_triangles': 12}, {'lod_index': 1, 'num_vertices': 16, 'num_triangles': 8}]}] Returns asset metadata with LOD information for mesh assets.

Get references for an asset Example output: [{'name': '/Game/Materials/M_Character.M_Character', 'class': 'Material'}, {'name': '/Game/Blueprints/BP_Player.BP_Player', 'class': 'Blueprint'}] Returns list of assets that reference the specified asset.

Run a console command in Unreal Example output: (No output for most commands, executed silently) Executes the console command without returning output.

Get detailed information about the current project Example output: {'project_name': 'MyGame', 'project_directory': '/Users/dev/MyGame/', 'engine_version': '5.3.0', 'total_assets': 1250, 'asset_locations': {'Game': 800, 'Engine': 450}, 'enhanced_input_enabled': true, 'input_actions': ['/Game/Input/IA_Move'], 'game_modes': ['/Game/Core/GM_Main'], 'characters': ['/Game/Characters/B_Hero'], 'maps': ['/Game/Maps/L_TestMap']} Returns comprehensive project metadata and asset counts.

Get detailed information about the current map/level Example output: {'map_name': 'TestMap', 'map_path': '/Game/Maps/TestMap', 'total_actors': 45, 'actor_types': {'StaticMeshActor': 20, 'DirectionalLight': 1, 'PlayerStart': 1}, 'lighting': {'has_lightmass_importance_volume': false, 'directional_lights': 1, 'point_lights': 3, 'spot_lights': 0}, 'streaming_levels': 0, 'streaming_level_names': []} Returns current level information with actor counts and lighting details.

Search for assets by name or path with optional class filter Example output: {'search_term': 'character', 'asset_class_filter': 'Blueprint', 'total_matches': 3, 'assets': [{'name': 'BP_Character', 'path': '/Game/Characters', 'class': 'Blueprint', 'package_name': 'BP_Character'}, {'name': 'BP_EnemyCharacter', 'path': '/Game/Enemies', 'class': 'Blueprint', 'package_name': 'BP_EnemyCharacter'}]} Returns search results with asset details, limited to 50 results.

Get all actors in the current world with their properties Example output: {'world_name': 'TestMap', 'total_actors': 45, 'actors': [{'name': 'StaticMeshActor_0', 'class': 'StaticMeshActor', 'location': {'x': 0.0, 'y': 0.0, 'z': 0.0}, 'rotation': {'pitch': 0.0, 'yaw': 0.0, 'roll': 0.0}, 'scale': {'x': 1.0, 'y': 1.0, 'z': 1.0}, 'is_hidden': false, 'folder_path': '/Meshes', 'components': ['StaticMeshComponent', 'SceneComponent']}]} Returns complete world outliner with all actors and their transform data.

Validate assets in the project to check for errors Example output: {'total_validated': 100, 'valid_assets': [{'path': '/Game/Meshes/SM_Cube', 'class': 'StaticMesh', 'size': '1024'}], 'invalid_assets': [{'path': '/Game/Missing/Asset', 'error': 'Asset does not exist'}], 'validation_summary': {'valid_count': 95, 'invalid_count': 5, 'success_rate': 95.0}} Returns validation results with asset status and error details.

Create a new object/actor in the world Example output: {'success': true, 'actor_name': 'StaticMeshActor_1', 'actor_label': 'MyCube', 'class': 'StaticMeshActor', 'location': {'x': 100.0, 'y': 200.0, 'z': 0.0}, 'rotation': {'pitch': 0.0, 'yaw': 45.0, 'roll': 0.0}, 'scale': {'x': 1.0, 'y': 1.0, 'z': 1.0}} Returns created actor details with final transform values.

Update an existing object/actor in the world Example output: {'success': true, 'actor_name': 'StaticMeshActor_1', 'actor_label': 'UpdatedCube', 'class': 'StaticMeshActor', 'location': {'x': 150.0, 'y': 200.0, 'z': 50.0}, 'rotation': {'pitch': 0.0, 'yaw': 90.0, 'roll': 0.0}, 'scale': {'x': 2.0, 'y': 2.0, 'z': 2.0}} Returns updated actor details with new transform values.

Delete an object/actor from the world Example output: {'success': true, 'message': 'Successfully deleted actor: MyCube', 'deleted_actor': {'actor_name': 'StaticMeshActor_1', 'actor_label': 'MyCube', 'class': 'StaticMeshActor', 'location': {'x': 100.0, 'y': 200.0, 'z': 0.0}}} Returns deletion confirmation with details of the deleted actor.

Take a screenshot of the Unreal Editor Example output: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA... Returns a base64-encoded PNG image of the current editor view. IF THIS ERRORS OUT MAKE SURE THE UNREAL ENGINE WINDOW IS FOCUSED

Move the viewport camera to a specific location and rotation for positioning screenshots

Overview

What is unreal-mcp?

unreal-mcp is an MCP server for Unreal Engine that connects to the built-in Unreal Python Remote Execution protocol. It allows AI agents or tools to control the Unreal Editor without installing a new plugin, giving access to the full Unreal Engine Python API.

How to use unreal-mcp?

Requires Unreal Engine 5.4+, Node.js with npx, and an MCP client (e.g., Claude). Enable the Python Editor Script Plugin and remote execution in your project settings. Add the server to your client configuration using npx -y @runreal/unreal-mcp. Tools like editor_run_python, editor_list_assets, editor_create_object, and editor_take_screenshot are available.

Key features of unreal-mcp

No new Unreal Engine plugin required; uses built-in remote execution
Execute arbitrary Python code inside the Unreal Editor
List, export, search, and validate assets
Create, update, and delete objects/actors in the world
Take screenshots and move the viewport camera

Use cases of unreal-mcp

—

FAQ from unreal-mcp

How is this different from other Unreal Engine MCP servers?

This server does not require installing a new UE plugin; it uses the built-in Python remote execution protocol. Adding new tools is faster since no C++ code is needed.

What are the runtime requirements?

Unreal Engine 5.4+ (verified, may work with earlier versions), Node.js with npx, and an MCP client like Claude or Cursor.

How do I enable remote execution in Unreal Engine?

Enable the “Python Editor Script Plugin” in Edit → Plugins, then in Edit → Project Settings enable “Enable Remote Execution” under the Python section.

What should I do if the server can’t connect to Unreal Editor?

Ensure the Python plugin and remote execution are enabled, try changing the bind address from 127.0.0.1 to 0.0.0.0 (allows local network connections), restart Unreal Editor fully, and restart your MCP client.