mcp-registry/Model Context Protocol for Unreal Engine

Model Context Protocol for Unreal Engine

Author: chongdashu

Description: Experimental MCP integration that lets AI assistant clients (Claude Desktop, Cursor, Windsurf) control Unreal Engine via natural language. Uses a UE C++ plugin exposing editor/engine actions over TCP and a Python MCP server (FastMCP) that registers tools for actor management, Blueprint creation/editing, Blueprint graph manipulation, and editor viewport control.

Stars: 1.6k

Forks: 241

License: MIT License

Category: Specialized

GitHub Documentation Twitter

Overview

Installation

### Prerequisites (from README)

- Unreal Engine 5.5+

- Python 3.12+

- An MCP Client (e.g., Claude Desktop, Cursor, Windsurf)

### Option A: Use the included sample project (`MCPGameProject`)

1. Right-click your `.uproject` file and **Generate Visual Studio project files**.

2. Open the generated solution (`.sln`).

3. Choose **Development Editor** as your build target.

4. Build the project (this includes the UnrealMCP plugin).

### Option B: Add the plugin to an existing Unreal project

1. Copy `MCPGameProject/Plugins/UnrealMCP` into your project’s `Plugins` folder.

2. In Unreal Editor: **Edit > Plugins** → find **UnrealMCP** (Editor category) → **Enable** → restart the editor when prompted.

3. Build the plugin:

- Right-click your `.uproject` → **Generate Visual Studio project files**

- Open solution (`.sln`)

- Build with your target platform and output settings

### Python server setup

- The repository README points to `Python/README.md` for detailed Python setup and how to run the MCP server.

### Configure your MCP client (from README)

Add an MCP server entry like this (replace `<path/to/the/folder/PYTHON>`):

{
  "mcpServers": {
    "unrealMCP": {
      "command": "uv",
      "args": [
        "--directory",
        "<path/to/the/folder/PYTHON>",
        "run",
        "unreal_mcp_server.py"
      ]
    }
  }
}

An example is in `mcp.json`.

### MCP configuration file locations (from README)

- Claude Desktop: `~/.config/claude-desktop/mcp.json` (Windows: `%USERPROFILE%\.config\claude-desktop\mcp.json`)

- Cursor: `.cursor/mcp.json` (project root)

- Windsurf: `~/.config/windsurf/mcp.json` (Windows: `%USERPROFILE%\.config\windsurf\mcp.json`)

FAQs

How does unreal-mcp's C++ plugin communicate with the Python MCP server on TCP port 55557?

The C++ plugin acts as the TCP server on port 55557, not the client. The Python MCP server connects as a TCP client, sending serialized commands the plugin executes against Unreal's engine. This inverts typical roles: the native plugin waits for connections while Python initiates them, translating MCP requests into TCP commands.

What are the differences between chongdashu/unreal-mcp and flopperam/unreal-engine-mcp, and which should I choose?

The core difference is architecture: chongdashu requires a C++ plugin installed in Unreal Editor, while flopperam is Python-only with no plugin dependency. Choose chongdashu if you need Blueprint graph manipulation tools and can manage plugin builds. Choose flopperam if you want faster setup without C++ compilation overhead or if your workflow emphasizes Python-side automation over deep editor integration.

Can I extend unreal-mcp with custom tools for project-specific Unreal Editor actions?

Yes. The Python server loads modules from the tools directory, allowing you to add custom tools that match your project's needs. Since the server uses FastMCP, you can define new tool functions with parameters, validation, and error handling that execute against the TCP plugin connection. This extension model supports project-specific workflows beyond the default actor, Blueprint, and viewport operations.

What are the most common setup issues when installing the UnrealMCP plugin and how do I fix them?

The most common setup issues are blocked port 55557, missing Visual Studio workload, absolute versus relative config paths, and plugin build failures. Fix them by checking firewall rules for local TCP, installing Visual Studio 2022's "Game Development with C++" workload, using full absolute paths in your MCP client config, and regenerating project files before rebuilding the plugin in Unreal Editor.

Does unreal-mcp support runtime or packaged game manipulation outside the Unreal Editor?

No. The current architecture targets editor-side control exclusively. Runtime or packaged-game manipulation is documented as a requested feature in the issue tracker, not a supported capability. The C++ plugin binds to editor subsystems and the TCP server operates within the editor process, preventing use in standalone builds.

Is unreal-mcp compatible with Unreal Engine 5.6 or only 5.5?

UE 5.5+ is the documented minimum requirement. UE 5.6 compatibility remains unresolved according to Issue #31 in the project tracker, meaning there's no confirmed support yet. If you need UE 5.6, check that issue thread for updates or test compatibility yourself in a non-production environment first.