SkillAgentSearch skills...

MCP Unreal

MCP server that gives AI coding agents (Claude Code, Cursor, etc.) full control over Unreal Engine 5.7 projects — headless builds & tests, Blueprint editing, actor manipulation, procedural mesh generation, and UE API documentation lookup.

GenerateConvertImprove

Install / Use

/learn @remiphilippe/MCP Unreal
About this skill

Quality Score

0/100

Supported Platforms

Claude Code
Claude Desktop
Cursor

README

mcp-unreal

CI Go 1.25+ License: Apache-2.0

MCP (Model Context Protocol) server that gives AI coding agents complete autonomous control over an Unreal Engine 5.7 project. Single Go binary, zero external dependencies.

Build, test, manipulate the editor, edit Blueprints, generate procedural meshes, and look up UE API documentation — all through 49 MCP tools that any MCP-compatible agent can call directly.

Quick Start

# Install
go install github.com/remiphilippe/mcp-unreal/cmd/mcp-unreal@latest

# Build the documentation index
mcp-unreal --build-index

# Register with your AI coding tool (see Setup section below)

Prerequisites

Installation

From Source

git clone https://github.com/remiphilippe/mcp-unreal.git
cd mcp-unreal
make build

Pre-built Binaries

Download from GitHub Releases — available for macOS, Linux, and Windows on both amd64 and arm64.

Enabling Remote Control API

The Remote Control API is a built-in UE plugin that provides HTTP access to actor properties and function calls on port 30010. mcp-unreal uses it for get_property, set_property, call_function, and move_actor tools.

  1. Open your project in Unreal Editor
  2. Go to Edit > Plugins
  3. Search for "Remote Control API"
  4. Check the Enabled checkbox
  5. Restart the editor when prompted

To verify it's running:

curl http://localhost:30010/remote/info

You should get a JSON response with the API version. If the connection is refused, the plugin is not enabled or the editor isn't running.

Install the UE Plugin

Copy the plugin/ directory into your project's Plugins/ folder:

cp -r plugin/ /path/to/YourProject/Plugins/MCPUnreal/

Rebuild the project. The plugin starts an HTTP server on port 8090 when the editor loads. See plugin/README.md for details.

Setup by Client

mcp-unreal works with any MCP-compatible AI coding tool. Below are setup instructions for each.

Note: Replace /path/to/mcp-unreal with the actual path to your built binary (e.g. the output of go install or make build). Set MCP_UNREAL_PROJECT to your .uproject file path or project root directory.

Claude Code

CLI registration:

claude mcp add mcp-unreal -- /path/to/mcp-unreal

Config file (.mcp.json at project root, or ~/.claude.json for global):

{
  "mcpServers": {
    "mcp-unreal": {
      "type": "stdio",
      "command": "/path/to/mcp-unreal",
      "env": {
        "MCP_UNREAL_PROJECT": "/path/to/MyProject/MyProject.uproject"
      }
    }
  }
}

Cursor

Config file (.cursor/mcp.json at project root, or ~/.cursor/mcp.json for global):

{
  "mcpServers": {
    "mcp-unreal": {
      "command": "/path/to/mcp-unreal",
      "env": {
        "MCP_UNREAL_PROJECT": "/path/to/MyProject/MyProject.uproject"
      }
    }
  }
}

After saving, enable via Cursor Settings > MCP Servers.

OpenAI Codex CLI

CLI registration:

codex mcp add mcp-unreal -- /path/to/mcp-unreal

Config file (.codex/config.toml at project root, or ~/.codex/config.toml for global):

[mcp_servers.mcp-unreal]
command = "/path/to/mcp-unreal"
args = []
tool_timeout_sec = 120

[mcp_servers.mcp-unreal.env]
MCP_UNREAL_PROJECT = "/path/to/MyProject/MyProject.uproject"

Increase tool_timeout_sec for build_project and run_tests which can take 60+ seconds.

VS Code with GitHub Copilot

Requires VS Code 1.99+ with GitHub Copilot Agent Mode enabled.

Config file (.vscode/mcp.json at project root):

{
  "servers": {
    "mcp-unreal": {
      "type": "stdio",
      "command": "/path/to/mcp-unreal",
      "env": {
        "MCP_UNREAL_PROJECT": "${workspaceFolder}"
      }
    }
  }
}

Windsurf

Config file (~/.codeium/windsurf/mcp_config.json):

{
  "mcpServers": {
    "mcp-unreal": {
      "command": "/path/to/mcp-unreal",
      "env": {
        "MCP_UNREAL_PROJECT": "/path/to/MyProject/MyProject.uproject"
      }
    }
  }
}

Cline (VS Code Extension)

Open the Cline panel > MCP Servers icon > Configure tab > Advanced MCP Settings, then add:

{
  "mcpServers": {
    "mcp-unreal": {
      "command": "/path/to/mcp-unreal",
      "env": {
        "MCP_UNREAL_PROJECT": "/path/to/MyProject/MyProject.uproject"
      }
    }
  }
}

Zed

Config file (~/.config/zed/settings.json):

{
  "context_servers": {
    "mcp-unreal": {
      "command": "/path/to/mcp-unreal",
      "env": {
        "MCP_UNREAL_PROJECT": "/path/to/MyProject/MyProject.uproject"
      }
    }
  }
}

Quick Reference

| Client | Config File | Top-level Key | |--------|-------------|---------------| | Claude Code | .mcp.json or ~/.claude.json | mcpServers | | Cursor | .cursor/mcp.json or ~/.cursor/mcp.json | mcpServers | | Codex CLI | .codex/config.toml or ~/.codex/config.toml | [mcp_servers.<name>] | | VS Code Copilot | .vscode/mcp.json | servers | | Windsurf | ~/.codeium/windsurf/mcp_config.json | mcpServers | | Cline | Extension-managed settings | mcpServers | | Zed | ~/.config/zed/settings.json | context_servers |

Recommended System Prompt

For best results, add the following to your project's system prompt (e.g. CLAUDE.md, .cursorrules, .codex/instructions.md, or equivalent). This tells the AI agent how to use the MCP tools effectively.

## Unreal Engine MCP Tools

This project uses mcp-unreal for AI-driven Unreal Engine development. The following MCP tools are available:

### Workflow Guidelines

1. **Always check status first**: Call `status` to verify the editor and plugin connections before attempting editor operations.
2. **Look up docs before writing UE code**: Use `lookup_class` to get class references (inheritance, properties, functions) and `lookup_docs` for API patterns before writing C++ or Blueprint logic.
3. **Build-test cycle**: After editing C++ files, call `build_project` to compile, then `run_tests` to verify. Read build errors carefully — use `lookup_docs` to understand UE APIs.
4. **Actor workflow**: Use `get_level_actors` to discover existing actors, `spawn_actor` to create new ones, `move_actor` to position them, and `set_property`/`get_property` to read/write properties.
5. **Blueprint workflow**: Use `blueprint_query` with operation `list` to find Blueprints, then `list_variables`/`list_functions`/`list_nodes` to inspect them. Use `blueprint_modify` to make changes, and always `compile` after modifications.
6. **Material workflow**: Use `material_ops` with `create` to make new materials, `get_parameters` to inspect existing ones, and `set_parameter` or `set_texture` to modify them.
7. **Save your work**: The editor does not auto-save. After making changes, use `level_ops` with `save_level` or remind the user to save.
8. **PIE testing**: Use `pie_control` with operation `start` to begin a Play In Editor session, `status` to verify it started, and `stop` to end it. Use `capture_viewport` with `include_ui=true` during PIE to see the game view with HUD/menus. Use `player_control` to move the player pawn (`teleport`, `set_rotation`) or reposition the editor viewport camera (`get_camera`, `set_camera`).

### Tool Modes

- **Headless tools** (`build_project`, `run_tests`, `cook_project`, etc.) do NOT require the editor to be running. They invoke UnrealEditor-Cmd directly.
- **Editor tools** (actors, blueprints, materials, etc.) require the Unreal Editor to be open with the MCPUnreal plugin loaded.
- **Documentation tools** (`lookup_docs`, `lookup_class`) are always available — use them liberally.

### Object Paths

Many tools require UE object paths. The format is:
- Actor paths: `/Game/Maps/MapName.MapName:PersistentLevel.ActorName`
- Asset paths: `/Game/Folder/AssetName`
- Engine assets: `/Engine/BasicShapes/Cube`

Use `get_level_actors` to discover actor paths, and `search_assets` to find asset paths.

Tip: For Claude Code, save this as CLAUDE.md in your project root. For Cursor, save as .cursorrules. For Codex, save as .codex/instructions.md.

Configuration

| Variable | Default | Description | |----------|---------|-------------| | UE_EDITOR_PATH | Platform-dependent | Path to UnrealEditor-Cmd binary | | MCP_UNREAL_PROJECT | Auto-detected from cwd | Path to .uproject file or project root | | RC_API_PORT | 30010 | UE Remote Control API HTTP port | | PLUGIN_PORT | 8090 | MCPUnreal editor plugin HTTP port | | MCP_UNREAL_LOG_LEVEL | info | Log level: debug, info, warn, error | | MCP_UNREAL_DOCS_INDEX | ./docs/index.bleve | Path to bleve documentation index |

Platform defaults for UE_EDITOR_PATH:

  • macOS: /Users/Shared/Epic Games/UE_5.7/Engine/Binaries/Mac/UnrealEditor-Cmd
  • Windows: C:\Program Files\Epic Games\UE_5.7\Engine\Binaries\Win64\UnrealEditor-Cmd.exe
  • Linux: /opt/UnrealEngine/Engine/Binaries/Linux/UnrealEditor-Cmd

Architecture

                                                    ┌───────────────────────┐
                                                    │   UE 5.7 Editor       │
                                                    │                       │

remiphilippe

View profile

View on GitHub
GitHub Stars10
CategoryDevelopment
Updated2d ago
Forks2
remiphilippe/mcp-unreal

Languages

Go

Security Score

95/100

Audited on Apr 4, 2026

No findings