UE5 MCP Server

An MCP (Model Context Protocol) server that bridges AI assistants to Unreal Engine 5's editor, enabling direct manipulation of levels, actors, Blueprints, and Animation Blueprints.

Why a Standalone Repository?

This MCP server was originally part of the UnrealClaude plugin, but has been moved to its own repository because:

1. Expanded Scope: The MCP protocol is an open standard now supported by many AI providers
2. Easier Forking: Developers can fork and adapt this bridge for other AI services without pulling the entire Unreal plugin
3. Community Contributions: Standalone repo makes it easier to accept PRs for new features, bug fixes, and support for additional MCP clients

Compatible AI Clients

This server uses the standard Model Context Protocol and works with any MCP-compatible AI client, including:

• Claude Code (CLI)
• Claude Desktop App
• OpenAI ChatGPT Desktop (MCP support added March 2025)
• Cursor (AI-powered IDE)
• Replit (AI coding platform)
• Sourcegraph Cody
• Windsurf
• And any other MCP-compliant tool

The protocol was donated to the Linux Foundation in December 2025 and continues to see broad adoption across the AI industry.

---

Important: What This Tool Is (and Isn't)

This is NOT a "text-to-game" tool. It will not generate 3D models, textures, animations, or replace the work of artists, animators, and asset creators.

This IS a workflow accelerator for Unreal Engine developers. It helps with:

• Project setup monotony: Quickly scaffold Blueprints, set up state machines, configure input bindings
• Repetitive editor tasks: Spawn actors, set properties, organize levels using natural language
• Rapid prototyping: Test ideas faster by describing what you want instead of clicking through menus
• Learning UE5: Query the built-in API documentation while working

The goal is to speed up the tedious parts of game development so you can focus on the creative work that actually matters.

---

Requirements

• Node.js 18.0.0 or higher
• An HTTP endpoint that implements the expected REST API (default: http://localhost:3000)

Note: This MCP server is designed to work with the UnrealClaude plugin, but can be adapted for other HTTP backends that implement the same API.

Quick Start

1. Install

git clone https://github.com/Natfii/unrealclaude-mcp-bridge.git
cd unrealclaude-mcp-bridge
npm install

2. Configure Your MCP Client

Add to your MCP client's configuration:

Claude Code (~/.claude/settings.json):

{
  "mcpServers": {
    "unreal": {
      "command": "node",
      "args": ["/path/to/unrealclaude-mcp-bridge/index.js"],
      "env": {
        "UNREAL_MCP_URL": "http://localhost:3000"
      }
    }
  }
}

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "unreal": {
      "command": "node",
      "args": ["/path/to/unrealclaude-mcp-bridge/index.js"],
      "env": {
        "UNREAL_MCP_URL": "http://localhost:3000"
      }
    }
  }
}

Other MCP Clients: Consult your client's documentation for MCP server configuration. The server uses stdio transport.

3. Use It

Once connected, you can interact with Unreal Editor through natural language:

"Spawn a point light at position 0, 0, 500"
"List all StaticMeshActors in the level"
"Create a new Actor Blueprint called BP_Enemy"
"Add a float variable called Health to BP_Player"
"Create a state machine called Locomotion in my Animation Blueprint"

---

Available Tools

Connection & Context

Tool	Description
unreal_status	Check connection to Unreal Editor
unreal_get_ue_context	Get UE 5.7 API documentation by category or query

Level & Actor Tools

Tool	Description
unreal_open_level	Open, create, or list level maps in the editor
unreal_spawn_actor	Spawn actors in the level
unreal_get_level_actors	List actors in the current level
unreal_set_property	Set properties on actors
unreal_move_actor	Move/rotate/scale actors
unreal_delete_actors	Delete actors from the level
unreal_run_console_command	Run Unreal console commands
unreal_get_output_log	Get recent output log entries

Asset Tools

Tool	Description
unreal_asset_search	Search for assets by class, path, or name
unreal_asset_dependencies	Get all assets that a specific asset depends on
unreal_asset_referencers	Get all assets that reference a specific asset

Script Execution

Tool	Description
unreal_execute_script	Execute C++, Python, or console scripts
unreal_cleanup_scripts	Remove generated scripts
unreal_get_script_history	Get script execution history

Viewport

Tool	Description
unreal_capture_viewport	Capture screenshot of active viewport

Blueprint Tools

Tool	Description
unreal_blueprint_query	Query Blueprint information (list, inspect, get_graph)
unreal_blueprint_modify	Modify Blueprints (create, add variables/functions, add nodes, connect pins)

Animation Blueprint Tools

Tool	Description
unreal_anim_blueprint_modify	Full Animation Blueprint manipulation

Character Tools

Tool	Description
unreal_character	Query and modify ACharacter actors in the current level
unreal_character_data	Create and manage character configuration DataAssets and stats DataTables

Material Tools

Tool	Description
unreal_material	Material instance creation and assignment for Skeletal Meshes

Enhanced Input Tools

Tool	Description
unreal_enhanced_input	Create and modify Enhanced Input assets (InputAction, InputMappingContext)

Async Task Queue

Tool	Description
unreal_task_submit	Submit an MCP tool for async background execution
unreal_task_status	Check status of a submitted async task
unreal_task_result	Get the result of a completed async task
unreal_task_list	List all async tasks
unreal_task_cancel	Cancel a running async task

---

Animation Blueprint Operations

The unreal_anim_blueprint_modify tool provides comprehensive control over Animation Blueprints:

State Machine Operations

Operation	Description
get_info	Get AnimBlueprint structure overview
get_state_machine	Get detailed state machine info
create_state_machine	Create new state machine
add_state	Add state to state machine
remove_state	Remove state from state machine
set_entry_state	Set entry state for state machine
connect_state_machine_to_output	Connect state machine to AnimGraph output pose

Transition Operations

Operation	Description
add_transition	Create transition between states
remove_transition	Remove transition
set_transition_duration	Set blend duration
set_transition_priority	Set evaluation priority

Transition Condition Graph

Operation	Description
add_condition_node	Add logic node (TimeRemaining, Greater, Less, And, Or, Not, GetVariable)
delete_condition_node	Remove node from transition graph
connect_condition_nodes	Connect nodes in transition graph
connect_to_result	Connect condition to transition result

Node/Pin Introspection

Operation	Description
get_transition_nodes	List all nodes in transition graph(s) with their pins
inspect_node_pins	Get detailed pin info (types, connections, default values)
set_pin_default_value	Set pin default value with type validation
add_comparison_chain	Add GetVariable -> Comparison -> Result chain
validate_blueprint	Return compile status and diagnostics

Animation Assignment

Operation	Description
set_state_animation	Assign AnimSequence, BlendSpace, BlendSpace1D, or Montage
find_animations	Search compatible animation assets

Batch Operations

Operation	Description
batch	Execute multiple operations atomically

---

UE 5.7 Context System

The server includes built-in UE 5.7 API documentation that can be queried:

Available Categories

Category	Description
animation	Animation Blueprint, state machines, transitions, UAnimInstance
blueprint	Blueprint graphs, UK2Node, FBlueprintEditorUtils
slate	Slate UI widgets, SNew/SAssignNew, layout patterns
actor	Actor spawning, components, transforms, iteration
assets	Asset loading, TSoftObjectPtr, FStreamableManager, async loading
replication	Network replication, RPCs, DOREPLIFETIME, OnRep
enhanced_input	Enhanced Input System, Input Actions, Mapping Contexts
character	Character movement, configuration, stats
material	Material instances, parameters, slots

Usage

// Get specific category
{ "category": "animation" }

// Search by keywords
{ "query": "state machine transitions" }

// List all categories
{}

Automatic Context Injection

Enable automatic context injection by setting:

{
  "env": {
    "INJECT_CONTEXT": "true"
  }
}

---

Configuration

Environment Variable	Default	Description
UNREAL_MCP_URL	http://localhost:3000	Unreal plugin HTTP server URL
MCP_REQUEST_TIMEOUT_MS	30000	Request timeout in milliseconds
INJECT_CONTEXT	false	Auto-inject UE5 context on tool responses
DEBUG	-	Enable debug logging

---

Troubleshooting

Tools show "NOT CONNECTED"

• Ensure your HTTP backend is running and accessible
• Verify the UNREAL_MCP_URL environment variable points to the correct endpoint
• Check that the endpoint responds to /mcp/status

stdin/stdout errors

• Ensure Node.js 18+ is installed and in PATH
• Run npm install to ensure dependencies are present
• Verify the path in your MCP client config points to the correct index.js

Running the Test Suite

This repo includes a Vitest test suite (87 tests) that validates bridge behavior without a running Unreal Editor:

npm install
npm test              # run all tests
npm run test:watch    # watch mode
npm run test:coverage # with coverage report

Tests mock the Unreal HTTP server and cover schema conversion, HTTP client logic, context loading, tool listing, and call routing.

---

Contributing

Contributions are welcome! Feel free to:

• Add support for additional MCP client configurations
• Improve the UE5 context documentation
• Fix bugs or add new features
• Submit documentation improvements

---

License

MIT with Attribution - see LICENSE for details.

Attribution Required: If you use this project, please credit:

• Project: UE5 MCP Server
• Author: Natali Caggiano (Natfii)
• Link: https://github.com/Natfii/unrealclaude-mcp-bridge

Disclosure Required: If you build another MCP server or AI integration using this code, please disclose its use in your documentation.

---

Related

• UnrealClaude Plugin - Unreal Engine plugin that provides the HTTP backend for this MCP server
• Model Context Protocol - The protocol specification
• MCP GitHub - Official MCP repositories and SDKs