home / mcp / unreal gen ai mcp server

Unreal Gen AI MCP Server

Provides an MCP server to control Unreal projects via external GenAI clients and run Python-driven actions.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "prajwalshettydev-unrealgenaisupport": {
      "command": "python",
      "args": [
        "<your_project_directoy_path>/Plugins/GenerativeAISupport/Content/Python/mcp_server.py"
      ],
      "env": {
        "UNREAL_HOST": "localhost",
        "UNREAL_PORT": "9877"
      }
    }
  }
}

You set up and run the Unreal Engine Generative AI MCP Server to connect Unreal projects with external GenAI services. The MCP server lets you spawn and transform scene objects, generate blueprints and functions, run Python scripts, and drive in-editor actions from an external client. This guide walks you through practical usage, installation, and important tips to keep your workflow secure and productive.

How to use

You connect an MCP client (such as Claude Desktop App or Cursor IDE) to the MCP Server that runs inside your Unreal project. Start the server locally and keep the host/port configuration in sync with your client. Once connected, you can spawn objects, move/rotate/scale them, change materials, spawn scene elements, and execute Python scripts or console commands from the client. You can also generate UI widgets and automate blueprint creation from prompts and structured outputs.

How to install

Prerequisites: you need Python installed on your system for the MCP server runner and the CLI. You also need Unreal Editor with the Python Editor Script Plugin enabled. The client you plan to use (Claude Desktop App or Cursor IDE) will connect to the local MCP server.

Step by step commands you can run to set up the MCP server workflow are shown below. Follow them exactly to ensure the server starts and the client can communicate with Unreal Engine.

# 1) Install the MCP CLI (required for some workflows)
pip install mcp[cli]

# 2) Enable the Python Editor Script Plugin in Unreal Editor
# (do this inside Unreal Editor: Edit > Plugins > Python Editor Script Plugin and enable it)

# 3) Prepare the MCP server runner in your project
# Use the explicit runner path shown in the examples below when configuring the client

Additional sections from the server guide

Configure MCP to run with a local Python-based server. The common pattern is to start the MCP server script from your Unreal project, then connect the client to the specified host and port.

{
  "mcpServers": {
    "unreal-handshake": {
      "command": "python",
      "args": ["<your_project_directoy_path>/Plugins/GenerativeAISupport/Content/Python/mcp_server.py"],
      "env": {
        "UNREAL_HOST": "localhost",
        "UNREAL_PORT": "9877"
      }
    }
  }
}

Security and startup notes

Before enabling MCP features, be aware of security implications. The MCP server can control an Unreal project, so limit access to trusted environments and use version control to track changes.

If you enable Autostart, the MCP server will launch when the editor starts. If you disable Autostart, start the server manually from the plugin’s Python directory and then start the client applications.

Available tools

SpawnObject

Spawn objects or shapes in the Unreal level from prompts or scripted actions.

TransformObject

Move, rotate, and scale objects as directed by the GenAI prompts.

MaterialChange

Change materials or colors of scene objects through generated instructions.

BlueprintGeneration

Auto-create blueprint graphs, functions, and variables to implement AI-driven behavior.

RunPython

Execute Python scripts in Unreal context from the MCP workflow.

RunConsole

Run console commands inside Unreal Editor as part of automated tasks.

UIWidgets

Generate UI widgets and related blueprint nodes from prompts.

ProjectFiles

Create or edit project folders and files as part of project evolution.