UnrealCopilot

# Unreal Copilot

MCP Server for analyzing and editing Unreal Engine 5 projects - Blueprint, Asset, C++ source code, and executable Skills.

Goal: Let AI understand the complete picture of an Unreal project by tracing reference chains across Blueprint ↔ C++ ↔ Asset boundaries, and execute editor operations via Skills.

中文文档

Features

• Blueprint Analysis: Hierarchy, dependencies, graph inspection, variables, components
• Blueprint Editing: Variables/graphs/nodes add-remove-update, pin linking/defaults, transactional batch operations
• Asset Reference Tracking: Find what uses what, and what is used by what
• C++ Source Analysis: Class structure, UPROPERTY/UFUNCTION detection (tree-sitter based)
• Cross-Domain Queries: Trace complete reference chains across all domains
• Editor Integration: Start/Stop MCP Server directly from Unreal Editor menu
• Scope Control: Search project-only, engine-only, or both
• Unified Search: grep-like interface across all domains
• Skill System: Discoverable, readable, executable editor capabilities

Blueprint Editing Plan

• Blueprint Write Capability Plan

Blueprint Editing Support

Blueprint write support is now available through CppSkillApiSubsystem + skills.

• Structure-level: add/remove/rename variable, set defaults, add/remove/rename graph
• Node-level: add/remove node, connect pins, set pin default value
• High-level node creation: add function-call nodes by function path
• Pin discovery: query node pins by node_guid before connecting
• Structured execution: execute_blueprint_operation / execute_blueprint_commands
• Diagnostics: failed step includes context (graph_name, node_guid, pin_name, failed_index, failed_op)

Minimal workflow:

1. Create or load a blueprint.
2. Add a function graph (optional).
3. Add function call node (for example PrintString).
4. Query pins and connect by exact pin names.
5. Compile and save that blueprint.

Quick Start (Recommended)

Prerequisites

• Unreal Engine 5.3+
• uv - Python package manager (required)

0. One-time dependency sync (recommended)

Auto-install is supported, but for the first run we strongly recommend syncing the Python dependencies manually before opening the editor (more reliable, easier to debug):

cd <PluginRoot>\Content\Python
uv sync

Then open Unreal Editor and start the MCP server.

1. Install the Plugin

Copy the UnrealCopilot folder to your Unreal project's Plugins/ directory:

YourProject/
├── Plugins/
│   └── UnrealCopilot/    ← this folder
│       ├── Source/
│       ├── Content/
│       ├── skills/       ← skill definitions
│       ├── Tools/
│       │   └── UnrealMCPHub/
│       │       └── Win64/
│       │           └── unreal-mcphub.exe
│       └── UnrealCopilot.uplugin

2. Configure uv Path

1. Open Unreal Editor
2. Go to Edit → Project Settings → Plugins → Unreal Copilot
3. Set Uv Executable to your uv installation path, e.g.:
   • Windows: C:\Users\YourName\.local\bin\uv.exe or C:\Users\YourName\anaconda3\Scripts\uv.exe
   • macOS/Linux: /usr/local/bin/uv or ~/.local/bin/uv

2.5 Recommended: pair it with UnrealMCPHub on Windows

UnrealMCPHub is a project-aware wrapper around MCPHub. It can bind the current .uproject, launch or reuse the correct editor instance, sync the active endpoint into MCPHub, and surface live status for the current project.

A ready-to-run Windows build is bundled in this plugin:

.\Tools\UnrealMCPHub\Win64\unreal-mcphub.exe setup
.\Tools\UnrealMCPHub\Win64\unreal-mcphub.exe launch --wait-seconds 30
.\Tools\UnrealMCPHub\Win64\unreal-mcphub.exe sync-mcphub

Important:

• unreal-mcphub.exe is now a single-file distribution. It links MCPHub directly as a Rust library and does not require a neighboring mcphub.exe.
• We recommend enabling Auto Start MCP Server in Project Settings -> Plugins -> Unreal Copilot.
• If auto-start is disabled, UnrealMCPHub can still launch the editor, but the MCP endpoint may stay offline until you start it manually inside the editor.
• If you prefer not to use UnrealMCPHub, the direct in-editor flow below still works.

3. Start MCP Server

1. In Unreal Editor menu: Tools → Unreal Copilot → Start MCP Server
2. Check Output Log / notifications for: MCP Server is running
3. Copy MCP URL via: Tools → Unreal Copilot → Copy MCP URL

4. Connect from Cursor

Add to your Cursor MCP settings (use the copied URL):

{
  "mcpServers": {
    "unreal-copilot": {
      "url": "http://127.0.0.1:19840/mcp"
    }
  }
}

Architecture

┌──────────────────────────────────────────────────────────────────┐
│                         AI Agent (Cursor)                        │
└────────────────────────────────┬─────────────────────────────────┘
                                 │ MCP Protocol
                                 ▼
┌──────────────────────────────────────────────────────────────────┐
│                    MCP Server (Python/FastMCP)                   │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │  Analysis Tools     │  Skill Tools                         │  │
│  │  (search, refs...)  │  (list/read/run_unreal_skill)        │  │
│  └────────────────────────────────────────────────────────────┘  │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │  C++ Analyzer (tree-sitter)  │  SkillRunner (Python)       │  │
│  └────────────────────────────────────────────────────────────┘  │
└────────────────────────────────┬─────────────────────────────────┘
                                 │ HTTP / import unreal
                                 ▼
┌──────────────────────────────────────────────────────────────────┐
│              UnrealCopilot Plugin (Editor)                       │
│  ┌─────────────────────────┐  ┌────────────────────────────────┐ │
│  │ Plugin HTTP API (:8080) │  │   CppSkillApiSubsystem         │ │
│  │   Blueprint/Asset API   │  │   (Asset/BP/World/Editor ops)  │ │
│  └─────────────────────────┘  └────────────────────────────────┘ │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │   MCP Server (UE Python) - Managed by McpServerSubsystem    │ │
│  └─────────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────┘

Port model:

• MCP Port defaults to 19840 and is the external MCP endpoint that Cursor/Codex connects to.
• UE Plugin Port defaults to 8080 and is the internal HTTP bridge used by the Python MCP server to call back into the plugin for Blueprint/asset/editor operations.
• These two ports are intentionally different; using the same port would make the two in-editor servers conflict.

Available Tools (11 total)

Analysis Tools (8)

Skill Tools (3)

Skill System

Skills are discoverable, documented editor capabilities that AI agents can find, understand, and execute.

Skill Directory Structure

UnrealCopilot/skills/
├── cpp_asset_api/           # Asset primitives documentation
│   ├── SKILL.md
│   └── docs/overview.md
├── cpp_blueprint_api/       # Blueprint primitives documentation
│   ├── SKILL.md
│   └── docs/overview.md
├── cpp_blueprint_write_api/ # Blueprint write operations (variables/graphs/nodes/batch)
│   ├── SKILL.md
│   ├── docs/overview.md
│   └── scripts/
│       ├── create_blueprint_with_components.py
│       ├── patch_graph_nodes.py
│       ├── batch_refactor_blueprints.py
│       ├── add_function_call_node.py
│       └── list_node_pins.py
├── cpp_world_api/           # World/Level primitives documentation
│   ├── SKILL.md
│   └── docs/overview.md
├── cpp_editor_api/          # Editor operations documentation
│   ├── SKILL.md
│   └── docs/overview.md
├── cpp_validation_api/      # Validation primitives documentation
│   ├── SKILL.md
│   └── docs/overview.md
└── skill_script/            # Example executable skill
    ├── SKILL.md
    └── scripts/echo_args.py

SKILL.md Format

---
name: cpp_asset_api
description: CppSkillApiSubsystem asset primitives (rename/duplicate/delete/save)
tags: [cpp, asset]
---

# CppSkillApiSubsystem - AssetOps

Documentation content...

Using Skills (Agent Workflow)

# 1. Discover available skills
skills = await list_unreal_skill()
# Returns: [{name, description, tags, skill_root}, ...]

# 2. Read skill documentation
doc = await read_unreal_skill(skill_name="cpp_asset_api")
# Returns: {content: "...", tree: ["SKILL.md", "docs/overview.md"]}

# 3. Read detailed API docs
api_doc = await read_unreal_skill(skill_name="cpp_asset_api", path="docs/overview.md")

# 4. Execute inline Python using the API
result = await run_unreal_skill(python="""
import unreal
api = unreal.get_editor_subsystem(unreal.CppSkillApiSubsystem)
success, error = api.rename_asset("/Game/OldName", "/Game/NewName")
RESULT = {"success": success, "error": error}
""")

CppSkillApiSubsystem Primitives

Blueprint Editing Example

import json
import unreal

api = unreal.get_editor_subsystem(unreal.CppSkillApiSubsystem)
bp_path = "/Game/Tests/BP_EditDemo"

# Add a callable function node in EventGraph
node_guid, error = api.add_blueprint_function_call_node(
    blueprint_path=bp_path,
    graph_name="EventGraph",
    function_path="/Script/Engine.KismetSystemLibrary.PrintString",
    node_pos_x=200,
    node_pos_y=120,
)

# Discover pin names before wiring
pins = json.loads(api.get_blueprint_node_pins(bp_path, "EventGraph", node_guid))

# Structured single-op write
report = json.loads(api.execute_blueprint_operation(
    blueprint_path=bp_path,
    operation_json=json.dumps({
        "op": "set_pin_default",
        "graph_name": "EventGraph",
        "node_guid": node_guid,
        "pin_name": "InString",
        "value_as_string": "Hello from Unreal Copilot",
    }),
    auto_compile=True,
    auto_save=True,
))

Plugin Settings

Example Usage

Analysis: Trace a GAS Ability

User: Help me trace how GA_Hero_Dash is triggered and executed

Agent:
[Uses search, get_hierarchy, get_blueprint_graph...]

GA_Hero_Dash complete flow:

Trigger path:
Player presses Shift → IA_Dash → IC_Default_KBM 
  → ULyraHeroComponent::Input_AbilityInputTagPressed()
  → ULyraAbilitySystemComponent::TryActivateAbility(Ability.Dash)

Execution logic (EventGraph):
1. ActivateAbility → IsLocallyControlled?
2. SelectDirectionalMontage → Set Direction
3. CommitAbility → PlayMontageAndWait
4. ApplyRootMotionConstantForce
5. Delay → EndAbility

Skill: Batch Rename Assets

User: Rename all blueprints in /Game/Characters/ that start with "Old_" to "New_"

Agent:
[Uses list_unreal_skill to find cpp_asset_api, read_unreal_skill to understand API]

result = await run_unreal_skill(python="""
import unreal

api = unreal.get_editor_subsystem(unreal.CppSkillApiSubsystem)
registry = unreal.AssetRegistryHelpers.get_asset_registry()

# Find matching assets
filter = unreal.ARFilter()
filter.package_paths = ["/Game/Characters"]
assets = registry.get_assets(filter)

renamed = []
for asset in assets:
    name = str(asset.asset_name)
    if name.startswith("Old_"):
        old_path = str(asset.package_name)
        new_path = old_path.replace("Old_", "New_")
        success, error = api.rename_asset(old_path, new_path)
        renamed.append({"old": old_path, "new": new_path, "success": success})

RESULT = {"renamed": renamed}
""")

Health Check

Verify the internal UE plugin HTTP bridge is running:

curl http://localhost:8080/health

Response:

{
  "ok": true,
  "status": "running",
  "plugin": "UnrealCopilot",
  "version": "0.3.1",
  "ue_version": "5.3.2-xxx",
  "project_name": "LyraStarterGame"
}

Development

# Install dev dependencies
uv sync --all-extras

# Run tests
uv run pytest

# Lint
uv run ruff check .

# Print config (debug)
uv run unreal-analyzer --print-config

Acknowledgements

This project was inspired by and references implementations from:

• unreal-analyzer-mcp - C++ source code analysis approach using tree-sitter
• ue5-mcp - Unreal Editor HTTP API exposure pattern

License

MIT