# chongdashu/unreal-mcp architecture

> Architecture diagram of the GitHub repository chongdashu/unreal-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chongdashu/unreal-mcp
- Repository: https://github.com/chongdashu/unreal-mcp

## Overview

- 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Unreal Engine Application"
        UE["MCPGameProject (Unreal Engine)"]:::component
        Plugin["UnrealMCP Plugin"]:::component
        UE -->|"contains"| Plugin
    end

    subgraph "Python MCP Server"
        Server["Python MCP Server"]:::component
        Tools["Python Tools Module"]:::component
        Server -->|"loads"| Tools
    end

    Clients["MCP Clients (ClaudeDesktop,Cursor,Windsurf)"]:::external
    DocConfig["Documentation & Configuration"]:::doc

    Clients -->|"sends_commands"| Server
    Server -->|"TCP_Port_55557"| Plugin
    Plugin -->|"sends_responses"| Server
    Server -->|"forwards_responses"| Clients
    DocConfig ---|"defines_settings"| Clients

    click UE "https://github.com/chongdashu/unreal-mcp/tree/main/MCPGameProject/"
    click Plugin "https://github.com/chongdashu/unreal-mcp/tree/main/MCPGameProject/Plugins/UnrealMCP/"
    click Server "https://github.com/chongdashu/unreal-mcp/blob/main/Python/unreal_mcp_server.py"
    click Tools "https://github.com/chongdashu/unreal-mcp/tree/main/Python/tools/"
    click DocConfig "https://github.com/chongdashu/unreal-mcp/tree/main/Docs/"

    classDef component fill:#AED6F1,stroke:#2471A3,stroke-width:2px;
    classDef external fill:#F9E79F,stroke:#F1C40F,stroke-width:2px;
    classDef doc fill:#A9DFBF,stroke:#27AE60,stroke-width:2px;
```
