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](#installation)
2. [Configuration](#configuration)
3. [MCP Tools](#mcp-tools)
4. [Blueprint Workflow Skill](#blueprint-workflow-skill)
5. [Troubleshooting](#troubleshooting)

---

## Installation

### Prerequisites

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

### Install from source

```bash
# 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

```bash
# 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:

```json
{
  "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:**
```json
{
  "filter": "all"  // "all", "blueprint", or "native"
}
```

**Output:**
```json
{
  "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:**
```json
{
  "asset_type": "Blueprint"  // optional filter
}
```

**Output:**
```json
{
  "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:**
```json
{
  "filter_blueprintable": true  // only Blueprintable classes
}
```

**Output:**
```json
[{
  "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:**
```json
{
  "class_name": "BP_Enemy",
  "location": [0, 0, 100],
  "rotation": [0, 90, 0],
  "properties": {"Health": 100}
}
```

**Output:**
```json
{
  "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:**
```json
{
  "include_components": true
}
```

**Output:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "crash_log": "Access violation at 0x00000...",
  "callstack": "Weapon.cpp:145..."
}
```

**Output:**
```json
{
  "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:**
```json
{
  "blueprint_path": "/Game/AI/BP_AIController"
}
```

**Output:**
```json
{
  "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:**
```json
{
  "file_path": "/Game/Characters/BP_Player"
}
```

**Output:**
```json
{
  "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:**
```json
{
  "cpp_class": "AWeapon",
  "blueprint_name": "BP_Weapon",
  "output_path": "/Game/Weapons"
}
```

**Output:**
```json
{
  "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:**
```json
{
  "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

```bash
# 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*