repository·main·Indexed 22 days ago
https://github.com/flopperam/unreal-engine-mcpA Model Context Protocol (MCP) server that enables AI agents in IDEs like Cursor and Claude Code to control the Unreal Engine editor via natural language. It offers a hosted service with 50+ advanced tools for Blueprint authoring, Materials, VFX, and Animation, as well as an open-source local version for basic scene manipulation, actor management, and world building.
The MCP server provides two categories of tools for working with Blueprints:
add_node: Add a node to a Blueprint graph (e.g., Print, Events, Variables).connect_nodes: Connect two nodes together to build execution flow and data connections.disconnect_nodes: Remove connections between nodes.create_variable: Add new properties/variables to your Blueprints.read_blueprint_content: Read the complete Blueprint structure (variables, functions, components, event graph).analyze_blueprint_graph: Analyze detailed graph structure including nodes, pins, and connections.get_blueprint_variable_details: Get variable information like types, defaults, and metadata.get_blueprint_function_details: Get function signatures, parameters, and graphs.The Flopperam Unreal Engine MCP follows a structured lifecycle for creating and editing Blueprints. For complex work, follow the full cycle. For trivial edits (like a single variable tweak), you can skip directly from reading to writing.
Full Cycle:
bp_brief or bp_inspect to understand the existing structure.bp_dry_run to validate intent or specs without making changes.bp_create to generate new assets.bp_commit to compile and layout the changes.bp_inspect or pie_test_bp to confirm structural and runtime correctness.Trivial Edit Shortcut:
bp_read_tool $\rightarrow$ bp_write_tool $\rightarrow$ bp_commit.
To optimize performance and avoid hitting constraints when using the Unreal Engine MCP, follow these efficiency rules:
queries, variables, components, nodes, edges, operations) to perform multiple operations in a single call.search_assets and scene_query simultaneously if they don't depend on each other).bp_inspect, material_inspect, widget_inspect, and animation_inspect to reduce data volume.bp_* tools, defer the compilation step. Batch your writes first, then call bp_commit once at the end.search_assets returns paths in PackageName.AssetName format. Always use the FULL path returned by this tool./Game/... paths; they resolve to nullptr if incorrect. Always resolve paths via search_assets first.scene_query returns actor labels, which are NOT asset paths.The Blueprint Graph tools consist of a high-performance C++ core and a Python MCP wrapper layer.
NodeManager.cpp: Handles node creation logic.BPConnector.cpp: Manages node connections.BPVariables.cpp: Handles variable creation and management.node_manager.py: Provides the add_node tool.connector_manager.py: Provides connect_nodes and disconnect_nodes tools.variable_manager.py: Provides the create_variable tool.Recommendation: Use batch operations where possible to minimize round-trip latency.
There are two distinct ways to integrate AI with Unreal Engine using MCP, depending on whether you want a managed service or a local open-source setup.
This is a managed service that uses a streamable HTTP MCP protocol. It connects your AI client (like Cursor, Claude Code, or Windsurf) to a hosted server, which then communicates via WebSockets to the FlopAI Unreal plugin. This setup provides access to over 50+ specialized tools covering Blueprint authoring, Scene & Level management, Materials, VFX, Animation, and more.
This is the version provided in this repository. It uses the stdio MCP protocol to connect your AI client to a local Python server (unreal_mcp_server_advanced.py). The Python server communicates with the UnrealMCP C++ plugin via a TCP socket. This setup is focused on core tools like World Building, Physics, Materials, Blueprint Systems, and Actor Management.
You can orchestrate multiple AI agents to work on different zones or districts of a single world.
Competition Pattern: Assign agents to specific coordinate zones (e.g., West vs East) and provide them with distinct toolsets and architectural styles to build competing cities.
Collaborative World Building: Assign specific districts to different agents (e.g., Agent 1 handles Residential with construct_house, Agent 2 handles Commercial with create_town, and Agent 3 handles Entertainment with create_maze).
### Collaborative World Building
**User Prompt:** *"Have multiple AIs work together to build different districts of the same city"*
**District Assignments:**
```bash
# AI 1: Residential District
construct_house(house_style="cottage", location=[-1000, -1000, 0])
construct_house(house_style="modern", location=[-500, -1000, 0])
construct_house(house_style="cottage", location=[-1000, -500, 0])
# AI 2: Commercial District
create_town(town_size="small", architectural_style="downtown", location=[0, 0, 0])
create_tower(height=15, base_size=5, tower_style="square", location=[200, 200, 0])
# AI 3: Entertainment District
create_maze(rows=10, cols=10, location=[1000, 0, 0])Understanding the Unreal Engine coordinate system for positioning actors:
The Flopperam Unreal Engine MCP follows a three-step pattern for scene and world building to ensure stability and correctness:
scene_brief for a high-level level overview, scene_query to find specific actors, or search_assets to find meshes and materials.scene_compose for batch actor placement/modification or use domain-specific tools (e.g., landscape_edit, foliage_edit) for specialized systems.scene_query with spatial filters to confirm placement, or pie_test_scene to test runtime behavior.Important Distinction:
search_assets) work on assets (reusable files in the Content Browser).There are two ways to use the Unreal Engine MCP. Choose based on your requirements for tool depth and setup complexity:
https://agent.flopperam.com/mcp.Python/ folder.Use Material Parameter Collections to manage global parameter sets that are accessible from any material. This is the recommended approach for implementing world-wide effects such as:
The Flopperam Unreal Engine MCP server controls a live Unreal Editor instance via WebSocket. All tools operate directly on the running editor. If you encounter connection errors, ensure the Unreal Editor is running and the FlopAI plugin is loaded.
To interact with the editor effectively, follow this three-step pattern:
bp_brief, scene_brief, search_assets, or project_context to understand the current state.bp_graph, material_edit, niagara_edit) to perform tasks.bp_inspect, actor_inspect) or run PIE (Play In Editor) tests to confirm runtime behavior.Before calling a tool, determine the user's intent to avoid accidental modifications: