Unreal Engine MCP (Model Context Protocol) Bridge
This project provides a bridge between text-based AI models and Unreal Engine 5.5+ using the Model Context Protocol (MCP). It allows you to control Unreal Engine using natural language commands and Python scripts.
Overview
The Unreal MCP Bridge enables:
- Creating and manipulating Blueprints
- Spawning and modifying actors in the level
- Working with Blueprint nodes and connections
- Managing project settings and input mappings
- Creating and modifying UMG widgets
- And much more!
Requirements
- Unreal Engine 5.5 or later with Python support enabled
- Python 3.10 or later
uvpackage manager (recommended) or pip
Installation
-
Clone this repository to your local machine
-
Install dependencies using
uv:
uv pip install -e .
Or using pip:
pip install -e .
- Make sure Unreal Engine is running with Python support enabled
Usage
Starting the MCP Server
To start the MCP server, run:
python unreal_mcp_server.py
This will start the server and register all available tools for interacting with Unreal Engine.
Using Example Scripts
The examples directory contains several example scripts that demonstrate how to use the MCP to interact with Unreal Engine:
add_cube.py: Spawns a cube actor in the level with customizable propertiescreate_rotating_cube_blueprint.py: Creates a Blueprint with a cube that rotates continuouslycreate_simple_game.py: Creates a simple game with a player character, collectibles, and score display
To run an example script:
python examples/add_cube.py
Available Tool Categories
The MCP Bridge provides tools in several categories:
Editor Tools
Tools for working with the Unreal Editor and actors in the level:
- Getting and finding actors
- Spawning and deleting actors
- Setting actor transforms and properties
- Taking screenshots
- Selecting actors
Blueprint Tools
Tools for creating and modifying Blueprint assets:
- Creating new Blueprints
- Adding and removing components
- Setting component properties
- Compiling Blueprints
Node Tools
Tools for working with Blueprint graph nodes and connections:
- Adding various node types (events, functions, variables)
- Connecting nodes
- Finding and deleting nodes
Project Tools
Tools for project-level operations:
- Creating input mappings
- Setting project settings
- Creating and managing levels
- Setting up GameModes
UMG Tools
Tools for creating and modifying UMG widgets:
- Creating Widget Blueprints
- Adding various widget types (Text, Button, Image, etc.)
- Binding widget events
- Managing widget properties
Extending the MCP
You can extend the MCP by adding new tools to the appropriate tool modules in the tools directory. Each tool should be registered with the MCP server in unreal_mcp_server.py.
Troubleshooting
- Make sure Unreal Engine is running before starting the MCP server
- Check that Python support is enabled in your Unreal Engine project
- Verify that the MCP server is running and listening for commands
- Look for error messages in the console output
License
This project is licensed under the MIT License - see the LICENSE file for details.