Unreal-mcp/docs/USER_GUIDE.md

Unreal MCP Server - User Guide

Complete guide for using Unreal MCP Server with Claude Code.

---

Table of Contents

1. Installation
2. Configuration
3. MCP Tools
4. Blueprint Workflow Skill
5. Troubleshooting

---

Installation

Prerequisites

• Python 3.11 or higher
• Claude Code
• Unreal Engine 5.3+ (optional, for runtime features)

Install from source

# Clone the repository
git clone https://github.com/AlexisTrouve/unreal-mcp.git
cd unreal-mcp

# Install the package
pip install -e .

# Or with development dependencies
pip install -e ".[dev]"

Verify installation

# Run tests
pytest

# Check if the module is importable
python -c "import unreal_mcp; print(unreal_mcp.__version__)"

---

Configuration

Claude Code Setup

The repository includes a .mcp.json file that configures Claude Code automatically.

Edit .mcp.json to set your Unreal project path:

{
  "mcpServers": {
    "unreal-mcp": {
      "command": "python",
      "args": ["-m", "unreal_mcp.server"],
      "env": {
        "UE_PROJECT_PATH": "C:/Path/To/Your/UnrealProject",
        "UE_COMMAND_PORT": "6776",
        "UE_MULTICAST_PORT": "6766"
      }
    }
  }
}

After editing, restart Claude Code or run /mcp to reload MCP servers.

Environment Variables

Create a .env file in the project root (copy from .env.example):

Variable	Default	Description
UE_PROJECT_PATH	-	Path to your Unreal project folder
UE_COMMAND_PORT	6776	TCP port for commands
UE_MULTICAST_GROUP	239.0.0.1	Multicast group for discovery
UE_MULTICAST_PORT	6766	Multicast port for discovery
LOG_LEVEL	INFO	Logging level

Unreal Editor Setup (Optional)

For runtime features (spawn actors, execute scripts), enable Python Remote Execution in Unreal:

1. Open your project in Unreal Editor
2. Go to Edit > Plugins
3. Enable Python Editor Script Plugin
4. Go to Edit > Project Settings > Python
5. Enable Enable Remote Execution
6. Set port to match your config (default: 6776)
7. Restart Unreal Editor

---

MCP Tools

Project Intelligence

get_spawnable_classes

List all spawnable classes in the project.

Input:

{
  "filter": "all"  // "all", "blueprint", or "native"
}

Output:

{
  "native_actors": [{"class_name": "ACharacter", "module": "Engine"}],
  "blueprint_actors": [{"name": "BP_Enemy", "path": "/Game/Enemies/BP_Enemy"}]
}

Example usage:

"What classes can I spawn in this project?"

---

get_project_assets

Get inventory of all project assets.

Input:

{
  "asset_type": "Blueprint"  // optional filter
}

Output:

{
  "total": 127,
  "by_type": {"Blueprint": 45, "Material": 30, "Texture": 52},
  "by_folder": {"Characters": ["BP_Player", "BP_Enemy"]}
}

Example usage:

"How many blueprints are in my project?"

---

scan_cpp_classes

Scan C++ classes in the Source folder.

Input:

{
  "filter_blueprintable": true  // only Blueprintable classes
}

Output:

[{
  "name": "AWeapon",
  "file": "Source/MyGame/Weapon.h",
  "parent": "AActor",
  "is_blueprintable": true
}]

Example usage:

"Find all Blueprintable C++ classes in my project"

---

Scene Manipulation

spawn_actor

Spawn an actor in the current level.

Input:

{
  "class_name": "BP_Enemy",
  "location": [0, 0, 100],
  "rotation": [0, 90, 0],
  "properties": {"Health": 100}
}

Output:

{
  "success": true,
  "actor_id": "BP_Enemy_3",
  "location": [0, 0, 100]
}

Example usage:

"Spawn 5 BP_Enemy actors in a circle around the player"

---

get_scene_hierarchy

Get the hierarchy of actors in the current level.

Input:

{
  "include_components": true
}

Output:

{
  "level": "MainLevel",
  "actors": [{
    "id": "BP_Enemy_1",
    "class": "BP_Enemy",
    "location": [100, 200, 0],
    "components": ["MeshComponent", "HealthComponent"]
  }]
}

Example usage:

"What actors are in the current level?"

---

modify_actor_transform

Modify an actor's position, rotation, or scale.

Input:

{
  "actor_id": "BP_Enemy_1",
  "location": [500, 0, 0],
  "rotation": [0, 180, 0],
  "scale": [2, 2, 2]
}

Example usage:

"Move BP_Enemy_1 to position 500, 0, 0"

---

Debug & Profiling

get_console_logs

Get Unreal Engine console logs.

Input:

{
  "filter": "Error",  // "All", "Error", "Warning"
  "limit": 50
}

Example usage:

"Show me the recent error logs"

---

analyze_crash_dump

Analyze a crash dump and suggest fixes.

Input:

{
  "crash_log": "Access violation at 0x00000...",
  "callstack": "Weapon.cpp:145..."
}

Output:

{
  "root_cause": "Null pointer dereference",
  "file": "Weapon.cpp",
  "line": 145,
  "fix_suggestion": "Add null check: if (Target && IsValid(Target)) {...}"
}

Example usage:

"Analyze this crash: [paste crash log]"

---

profile_blueprint

Profile a Blueprint's performance.

Input:

{
  "blueprint_path": "/Game/AI/BP_AIController"
}

Output:

{
  "avg_tick_time_ms": 2.3,
  "hotspots": [{"node": "Event Tick", "cost_ms": 1.8}],
  "optimization_potential": "HIGH"
}

Example usage:

"Profile BP_AIController for performance issues"

---

Blueprint Operations

read_blueprint

Parse a Blueprint .uasset file.

Input:

{
  "file_path": "/Game/Characters/BP_Player"
}

Output:

{
  "class_name": "BP_Player",
  "parent_class": "ACharacter",
  "variables": ["Health", "Speed"],
  "functions": ["Fire", "Reload"],
  "events": ["OnDeath"]
}

Example usage:

"What variables and functions does BP_Player have?"

---

create_blueprint_from_cpp

Create a Blueprint from a C++ class.

Input:

{
  "cpp_class": "AWeapon",
  "blueprint_name": "BP_Weapon",
  "output_path": "/Game/Weapons"
}

Output:

{
  "success": true,
  "blueprint_path": "/Game/Weapons/BP_Weapon"
}

Example usage:

"Create a Blueprint from my AWeapon C++ class"

---

execute_python_script

Execute a Python script in Unreal Editor.

Input:

{
  "script": "import unreal; print(unreal.EditorLevelLibrary.get_all_level_actors())"
}

Example usage:

"Run this Python script in Unreal: [script]"

---

Blueprint Workflow Skill

The /blueprint-workflow skill provides high-level Blueprint operations.

Commands

/blueprint-workflow analyze <path>

Analyze a Blueprint for performance issues.

/blueprint-workflow analyze BP_Enemy.uasset

Output:

• Performance issues (tick cost, casts, etc.)
• Optimization suggestions
• Complexity score

---

/blueprint-workflow bp-to-cpp <path>

Convert a Blueprint to C++ code.

/blueprint-workflow bp-to-cpp BP_Enemy.uasset

Output:

• Header file (.h)
• Implementation file (.cpp)
• Conversion notes

---

/blueprint-workflow cpp-to-bp <class> [name] [path]

Generate a Blueprint from a C++ class.

/blueprint-workflow cpp-to-bp AWeapon BP_Weapon /Game/Weapons

Output:

• Blueprint created in Unreal
• Exposed properties list
• Callable functions list

---

/blueprint-workflow transform <path> "<description>"

Transform a Blueprint with AI-powered modifications.

/blueprint-workflow transform BP_Character.uasset "add dash ability with cooldown"

Output:

• Modified Blueprint
• New variables/functions added
• Implementation details

---

/blueprint-workflow optimize <path>

Automatically optimize a Blueprint.

/blueprint-workflow optimize BP_AIController.uasset

Output:

• Performance before/after
• Optimizations applied
• Generated C++ (if beneficial)

---

Troubleshooting

MCP Server not appearing in Claude Code

1. Check .mcp.json is in the project root
2. Verify Python path: which python or where python
3. Run /mcp in Claude Code to reload servers
4. Check Claude Code logs for errors

"Not connected to Unreal Editor"

The server works in two modes:

1. Online mode: Connects to running Unreal Editor
2. Offline mode: Works with project files only

For online mode:

• Ensure Unreal Editor is running
• Enable Python Remote Execution in Project Settings
• Check port matches config (default: 6776)
• Firewall may block UDP multicast

"No Unreal nodes discovered"

1. Check Unreal Editor is running
2. Verify Python Editor Script Plugin is enabled
3. Check Remote Execution is enabled in Project Settings
4. Ensure ports match (6766 for discovery, 6776 for commands)
5. Try restarting Unreal Editor

"Parse error" on .uasset files

• File may be from a different Unreal version
• File may be corrupted
• Some asset types aren't fully supported

Python import errors

# Reinstall the package
pip uninstall unreal-mcp
pip install -e .

Port conflicts

Change ports in .env or .mcp.json:

UE_COMMAND_PORT=6777
UE_MULTICAST_PORT=6767

Remember to update Unreal Project Settings to match.

---

Examples

Example 1: Debug a crash

User: My game crashes when I shoot. Here's the log:
[paste crash log]

Claude: [Uses analyze_crash_dump]
The crash is a null pointer dereference in Weapon.cpp:145.
The CurrentTarget variable is null when firing.

Suggested fix:
if (CurrentTarget && IsValid(CurrentTarget))
{
    // Safe to use CurrentTarget
}

Example 2: Optimize a Blueprint

User: /blueprint-workflow analyze BP_AIController

Claude: [Analyzes Blueprint]

## Performance Analysis: BP_AIController

### Issues Found
🔴 HIGH: Event Tick with 23 operations/frame
   → Move pathfinding to timer-based updates

🟡 MEDIUM: 5 Cast nodes found
   → Replace with Blueprint Interfaces

### Recommendation
Convert to C++ for +180% performance gain.

Example 3: Generate code

User: Create a C++ health component with damage and healing

Claude: [Generates HealthComponent.h and HealthComponent.cpp]

// HealthComponent.h
UCLASS(ClassGroup=(Custom), meta=(BlueprintSpawnableComponent))
class MYGAME_API UHealthComponent : public UActorComponent
{
    GENERATED_BODY()

public:
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Health")
    float MaxHealth = 100.0f;

    UFUNCTION(BlueprintCallable, Category = "Health")
    void ApplyDamage(float Damage);

    UFUNCTION(BlueprintCallable, Category = "Health")
    void Heal(float Amount);
    ...
};

---

Support

• GitHub Issues: https://github.com/AlexisTrouve/unreal-mcp/issues
• Documentation: https://github.com/AlexisTrouve/unreal-mcp/docs

---

Last updated: 2026-01-20