# 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`:

```bash
uv pip install -e .
```

Or using pip:

```bash
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:

```bash
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:

```bash
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.