MCP-Unreal

The MCP-Unreal server enables remote interaction with Unreal Engine instances by exposing a Python execution environment over MCP. It automatically discovers Unreal nodes via multicast, reports real-time status, and allows clients to manage Unreal instances, execute Python code, and perform file-execution or statement evaluation in attended or unattended modes. Clients can connect using the provided multicast settings, request resource information, and send code for execution or evaluation through standard MCP tools. This server is designed to integrate with LSP-compatible clients for resource listing and to provide detailed logging for monitoring node health and execution outcomes.

To use the server, start it locally with the Python module entry point and then connect your MCP client to the multicast group and port configured in the server. You can issue two primary tool actions: Connect to Unreal Instance and Execute Python Code. Connect lets you discover and select an Unreal node by its multicast address and node_id; Execute Python Code lets you send Python snippets or files to run inside the selected Unreal Engine environment. For unattended execution, set the unattended flag to true so code runs without interactive prompts, and review the results via the server logs or client responses.

Prerequisites:

• Python 3.8+ installed on the host
• Internet access to install Python dependencies

Installation steps:

1. Clone the repository: git clone https://github.com/your-org/mcp-unreal-server.git cd mcp-unreal-server

2. Create and activate a virtual environment (optional but recommended): python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate

3. Install dependencies: pip install -r requirements.txt

4. Start the server: python -m src.mcp_server_unreal.server

5. Verify startup in logs and ensure the server is listening for multicast discovery.

Tips and common issues:

• Multicast discovery relies on network visibility; ensure multicast traffic is allowed on the network and that the Unreal MCP plugin is active.
• If no nodes are discovered, verify Unreal instances are running MCP-enabled plugins and that the multicast group/port match the defaults configured in RemoteExecutionConfig.
• For persistent logging, check mcp_unreal.log as configured in the server; adjust log levels if you need more verbosity during debugging.
• When executing code, prefer unattended mode for automated tasks and ensure proper error handling in your code to surface exceptions back to the client.
• If you modify multicast or logging settings in server.py, restart the server to apply changes.