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
• uv package manager (recommended) or pip

Installation

1. Clone this repository to your local machine

2. Install dependencies using uv:

uv pip install -e .

Or using pip:

pip install -e .

3. 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 properties
• create_rotating_cube_blueprint.py: Creates a Blueprint with a cube that rotates continuously
• create_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.