Unreal Engine MCP server

UnrealMCP is an Unofficial Unreal Engine plugin that implements the Machine Control Protocol (MCP), allowing AI assistants like Claude for Desktop and Cursor to interact with and manipulate Unreal Engine programmatically. The plugin creates a communication bridge that enables AI tools to perform various operations within your Unreal projects.

Installation

Quick Setup

1. Clone or download this repository as a zip
2. Create a new Unreal Project, or open an existing one
3. Create a "Plugins" folder in your project directory if it doesn't exist
4. Unzip or copy this repository into the Plugins folder

For Claude for Desktop Users

1. Run setup_unreal_mcp.bat in the MCP folder

2. Open your Unreal project and enable the plugin in Edit > Plugins (if not already enabled)

3. The script should automatically configure Claude for Desktop, but if needed, manually edit:

   Windows: %APPDATA%\Claude\claude_desktop_config.json

   {
       "mcpServers": {
           "unreal": {
               "command": "C:/path/to/your/project/Plugins/UnrealMCP/MCP/run_unreal_mcp.bat",
               "args": []
           }
       }
   }
   

For Cursor Users

1. Run setup_cursor_mcp.bat in the MCP folder

2. Open your Unreal project and enable the plugin in Edit > Plugins (if not already enabled)

3. If needed, manually edit:

   Windows: %APPDATA%\Cursor\User\settings.json

   {
       "mcp": {
           "enabled": true,
           "servers": {
               "unreal": {
                   "command": "C:/path/to/your/project/Plugins/UnrealMCP/MCP/run_unreal_mcp.bat",
                   "args": []
               }
           }
       }
   }
   

Usage

In Unreal Editor

1. Launch Unreal Editor with your project
2. The MCP controls can be found in the editor toolbar button
3. You can start/stop the TCP server from here
4. Check the output log under log filter LogMCP for additional information

With AI Assistants

1. Start your Unreal project with the plugin enabled
2. Open Claude for Desktop or Cursor
3. Verify that the tools have successfully enabled
4. Ask your AI assistant to work in Unreal

Example Prompts to Try:

• "What actors are in the current level?"
• "Create a cube at position (0, 0, 100)"
• "List available commands I can use with Unreal Engine"

Client-Side Integration

You can also use the provided Python scripts to interact with Unreal Engine programmatically:

from unreal_mcp_client import UnrealMCPClient

# Connect to the Unreal MCP server
client = UnrealMCPClient("localhost", 13377)

# Example: Create a cube in the scene
client.create_object(
    class_name="StaticMeshActor",
    asset_path="/Engine/BasicShapes/Cube.Cube",
    location=(0, 0, 100),
    rotation=(0, 0, 0),
    scale=(1, 1, 1),
    name="MCP_Cube"
)

Command Reference

The plugin supports various commands for scene manipulation:

• get_scene_info: Retrieve information about the current scene
• create_object: Spawn a new object in the scene
• delete_object: Remove an object from the scene
• modify_object: Change properties of an existing object
• execute_python: Run Python commands in Unreal's Python environment

Security Considerations

⚠️ IMPORTANT: This plugin allows AI agents to directly modify your Unreal Engine project.

Safety Measures:

• Always use source control (Git or Perforce) with your project
• Make regular backups of your project
• Test the plugin in a separate project first
• Review changes before committing them

Troubleshooting

• Ensure Unreal Engine is running with the MCP plugin enabled
• Check logs in Claude for Desktop or Cursor for stderr output
• Verify the TCP server is running in the Unreal Editor
• For additional help, join the Discord: https://discord.gg/abRftdSe

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.