MCP HubMCP Hub
runeape-sats

unreal-mcp

by: runeape-sats

Unreal Engine MCP server for Claude Desktop (early alpha preview)

10created 14/03/2025
Visit
Unreal
Desktop

📌Overview

Purpose: To enable Claude Desktop to generate and manipulate 3D objects in Unreal Engine 5.3 using natural language through a Model Context Protocol (MCP) Python server.

Overview: This framework establishes an interface between Claude Desktop and Unreal Engine, allowing users to create and modify 3D scenes in Unreal Engine based on text prompts, marking a significant leap towards text-to-game-generation technology.

Key Features:

  • Basic Object Creation: Users can create various primitive shapes (cubes, spheres, etc.) with customizable parameters such as position, rotation, scale, colors, and materials, facilitating straightforward 3D environment setup.

  • Blueprint Actor Creation: Allows the spawning of actors from Blueprint classes, supporting the creation of complex assets like buildings and props with specific parameters, enhancing creative possibilities for users.

  • Scene Manipulation: Provides functionality to modify existing objects in the scene, offering capabilities to change their transforms, colors, materials, and visibility, thus enabling dynamic scene management.

  • Asset Discovery: Facilitates searching for and listing available assets within a project, allowing users to filter by asset type and path to easily find necessary resources for their scenes.

Unreal Engine MCP Server for Claude Desktop

This repository contains a Model Context Protocol (MCP) Python server that allows Claude Desktop to interact with Unreal Engine 5.3 (via Remote Control API), creating and manipulating 3D objects based on text prompts. This integration enables Claude to build and modify 3D scenes in Unreal Engine through natural language, representing an early step toward text-to-game-generation technology.

Current Features

  • Use Claude Desktop text prompts to arrange assets in Unreal Engine Editor
  • Create static meshes for assembling primitive shapes
  • Look up Unreal project folder for assets

Quick Start

1. Requirements

  • Python 3.10+
  • Unreal Engine 5.3 with Remote Control API (plugin) enabled
  • Claude Desktop (Windows)

2. Installation

Clone the repository and install required packages:

git clone https://github.com/runeape-sats/unreal-mcp.git
cd unreal-mcp
pip install uv mcp requests

3. Configure Claude Desktop

Go to Claude Desktop → File → Settings → Developer → Edit Config claude_desktop_config.json and add the following, adjusting the path to your local repository:

{
  "mcpServers": {
    "unreal-mcp": {
      "command": "uv",
      "args": ["--directory", "\\path\\to\\unreal-mcp", "run", "unreal_mcp_server.py"],
      "env": {}
    }
  }
}

If you already have other MCP servers configured (like blender-mcp), you may need to disable them to avoid conflicts.

4. Launch Unreal Engine

Open Unreal Engine with your project and ensure the Remote Control API plugin is enabled.

5. Launch Claude Desktop

Restart Claude Desktop (fully exit and relaunch) to load the new configuration. Verify connection by asking Claude to create objects in Unreal Engine.

Project Structure

  • unreal_mcp_server.py - Main entry point that registers MCP tools
  • unreal_connection.py - Handles communication with Unreal Engine
  • unreal_actors.py - Functions for creating and manipulating actors
  • unreal_assets.py - Functions for working with assets and level info
  • unreal_utils.py - Utility functions and constants

Features

Basic Object Creation

Create primitive shapes with parameters: cubes, spheres, cylinders, planes, cones; custom position, rotation, scale, colors, and materials.

Example prompt:
Create a red cube at position 100, 200, 50

Blueprint Actor Creation

Spawn actors from Blueprint classes such as buildings, props, characters, with customizable parameters.

Example prompt:
Spawn a bench from the blueprint at /Game/CustomAsset/Blueprints/BP_Bench01

Scene Manipulation

Modify existing objects: change position, rotation, scale, colors, materials, and toggle visibility.

Example prompt:
Move the cube to position 0, 0, 100 and rotate it 45 degrees

Asset Discovery

Search and list available assets by type, path, or matching terms.

Example prompt:
List all bench static meshes in the project

Example Prompts

Create a blue sphere at position 0, 100, 50 with scale 2, 2, 2

Create a scene with a red cube at 0,0,0, a green sphere at 100,0,0, and a blue cylinder at 0,100,0

List all blueprint assets in the /Game/CustomAsset folder

Get information about the current level

Create a cylinder and then change its color to yellow

Troubleshooting

Connection Issues

  • Ensure Unreal Engine is running before starting the MCP server
  • Confirm Remote Control API plugin is enabled in Unreal Engine
  • Check if port 30010 is in use
  • Verify firewall settings do not block the connection

Objects Not Appearing

  • Check Unreal Engine output log for errors
  • Make sure objects are created within reasonable coordinates
  • Simplify prompts to isolate problems

Logging

The server logs detailed information to the console. Check logs for error messages and tracebacks when issues arise.

Development

To run the server in development mode:

pip install mcp[cli]
mcp dev unreal_mcp_server.py

Contributing

Contributions are welcome! Potential areas for improvement include:

  • Enhanced natural language processing for scene descriptions
  • More complex object creation capabilities
  • Support for additional Unreal Engine features
  • Improved error handling and feedback

License

MIT License