unreal

The Unreal MCP server enables natural language control of Unreal Engine workflows by exposing a set of tool modules (actor management, blueprint development, blueprint node graph manipulation, and editor viewport control) through the Model Context Protocol. You connect an MCP client such as Claude Desktop, Cursor, or Windsurf to the Python MCP server, which talks to the Unreal plugin over TCP (port 55557) and executes commands in Unreal based on your natural language prompts. The server loads tool modules from the Python/tools directory, handles command serialization, and returns structured responses to the client. To start using it, run the Python MCP server and connect your MCP client with the provided configuration so the client can issue actor/blueprint-related actions through natural language queries.

Prerequisites

• Unreal Engine 5.5+ and a compatible project (with the UnrealMCP plugin) installed
• Python 3.12+ installed on your system
• An MCP client (e.g., Claude Desktop, Cursor, Windsurf)

Installation steps

1. Clone or download the Unreal MCP repository containing the UnrealMCP plugin and Python server
2. Ensure Unreal Engine is installed and your project contains the UnrealMCP plugin at Plugins/UnrealMCP
3. Build the plugin for your project: open the project in Unreal Editor, enable the UnrealMCP plugin, and rebuild the project
4. Set up the Python MCP server as described in the Python README within the repository
5. Start the Python MCP server using the uv-based command configuration (see mcp_config for details)

Example commands

• Create a Python virtual environment and install dependencies (adjust to your system paths): python3 -m venv venv source venv/bin/activate pip install -U pip pip install fastmcp # if required by the project

• Run the MCP server (example, adjust the path to unreal_mcp_server.py): uv --directory <path/to/the/folder/PYTHON> run unreal_mcp_server.py

Notes and tips:

• This project is marked EXPERIMENTAL; expect breaking changes and potential instability.
• Verify Unreal Engine and the UnrealMCP plugin are correctly enabled and loaded in your Unreal project.
• The Python MCP server communicates with the Unreal plugin over TCP (port 55557); ensure firewall rules allow this traffic.
• If you need to customize tool behavior, review the modules under Python/tools and add or adjust tool implementations as needed.
• The recommended MCP client configuration uses the unrealMCP server name and the uv command as shown in the example mcp.json snippet.
• If you encounter connection issues, confirm that the Unreal Editor is running, the plugin is loaded, and the Python server process is active.
• For troubleshooting, check server logs and verify that the Python environment has the required dependencies and access to the Unreal project files.