How chongdashu/unreal-mcp works
• Unreal Engine Project (MCPGameProject):
• Represents the primary game project built in Unreal Engine.
• Contains the “UnrealMCP” plugin which resides in MCPGameProject/Plugins/UnrealMCP. This plugin implements the TCP server on the C++ (native) side, integrates with Unreal Editor subsystems, and offers actor, blueprint, and editor command functionalities.
• Python MCP Server:
• Located under Python/ (with its main entry defined in Python/unreal_mcp_server.py).
• Uses the FastMCP library to manage TCP socket connections (port 55557), command serialization, dynamic module/tool (actor_tools, blueprint_tools, etc.) loading from the Python/tools directory, and error/connection handling.
• MCP Clients:
• Although not part of the file tree, the README references clients like Claude Desktop, Cursor, and Windsurf that send natural language commands.
• Documentation and Configuration:
• Documentation files are under Docs/.
• The mcp.json and additional client-specific configurations detail how the clients should connect to the MCP servers.
Relationships and Data Flow
• Directional Flow from MCP Client to Python MCP Server:
• The client sends natural language commands configured via mcp.json.
• These commands are serialized and routed from the Python MCP server over TCP.
• Communication Between Python MCP Server and Unreal Engine Plugin:
• The Python server, through its TCP connection on port 55557, interacts with the UnrealMCP plugin.
• The plugin receives these commands and uses Unreal Engine subsystems to manipulate actors, blueprints, or editor settings.
• Bi-Directional Response Flow:
• The plugin communicates back to the Python server with command execution responses, which are then passed on to the MCP client.
Architectural Patterns and Design Principles
• Modular Architecture:
• Separation between the game engine (and its plugin) and the standalone Python server facilitates modular development and easier testing.
• Client-Server Communication:
• The TCP protocol over a dedicated port provides a clear communication channel.
• Clear separation of concerns exists: the Python server for command handling and integration with external clients, and the UnrealMCP plugin for direct Unreal Engine operations.
• Plugin Integration:
• The plugin architecture within the Unreal project leverages the extensibility of Unreal Engine to hook into editor subsystems.
Technologies and Frameworks to Emphasize
• Unreal Engine 5.5+ and its editor integration.
• C++ and Unreal Engine plugin system for UnrealMCP.
• Python 3.12+ used in the Python MCP server.
• FastMCP library (for protocol implementation).
• TCP socket programming for inter-process communication.