Unreal Engine

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.

# 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)

- Go 1.25+—install
- Unreal Engine 5.7— for build/test tools and editor interaction
- Remote Control API plugin— enabled in UE (seeEnabling Remote Control APIbelow)
- MCPUnreal editor plugin— for advanced editor tools (seeplugin/README.md)

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

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

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

Rebuild the project. The plugin starts an HTTP server on port 8090 when the editor loads. Seeplugin/README.mdfor details.

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

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

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

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

[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"

Increasetool_timeout_secforbuild_projectandrun_testswhich can take 60+ seconds.

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

Config file(.vscode/mcp.jsonat project root):

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

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

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

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" } } } }

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

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

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 asCLAUDE.mdin your project root. For Cursor, save as.cursorrules. For Codex, save as.codex/instructions.md.

- 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

┌───────────────────────┐ │ UE 5.7 Editor │ │ │ │ ┌─────────────────┐ │ │ │ Remote Control │ │ ┌────►│ │ API (port 30010)│ │ │ │ │ (built-in) │ │ │ │ └─────────────────┘ │ ┌──────────────┐ stdio ┌──────────────┐│ │ │ │ AI Coding │ JSON-RPC │ ││ │ ┌─────────────────┐ │ │ Agent │◄────────────►│ mcp-unreal │├────►│ │ MCPUnreal │ │ │ (Claude Code │ │ (Go binary) ││ │ │ Plugin (port │ │ │ Cursor, etc)│ │ ││ │ │ 8090) │ │ └──────────────┘ │ 49 tools │┘ │ │ • Actors │ │ │ doc index │ │ │ • Blueprints │ │ │ │ │ │ • Materials │ │ │ ┌──────────┐ │ │ │ • PCG / GAS │ │ │ │ Headless │ │ │ │ • Niagara │ │ │ │ exec.Cmd │─┼──────│──│ • Mesh ops │ │ │ └──────────┘ │ │ │ • Levels │ │ │ │ │ └─────────────────┘ │ │ ┌──────────┐ │ │ │ │ │ Bleve │ │ └───────────────────────┘ │ │ Doc Index│ │ │ └──────────┘ │ ┌───────────────────────┐ │ │──────│ docs/ │ └──────────────┘ │ ├── ue5.7/ │ │ ├── realtimemesh/ │ │ └── index.bleve │ └───────────────────────┘

- Headless—exec.CommandinvokesUnrealEditor-Cmdfor builds, tests, and cooking. No editor needed.
- Remote Control API— HTTP PUT tolocalhost:30010for property access and function calls. Built into UE.
- MCPUnreal Plugin— HTTP POST tolocalhost:8090for Blueprint editing, asset queries, mesh ops, and other deep editor internals.

SeeIMPLEMENTATION.mdfor the full architecture document.

To add custom documentation, place markdown files in thedocs/directory and rebuild the index. Seedocs/README.md.

You: "Build the project, fix any errors, and run the tests" Agent calls: 1. status() → editor + plugin online 2. build_project() → finds 2 compile errors 3. lookup_class("AActor") → looks up the correct API 4. (edits the C++ source) 5. build_project() → clean build 6. run_tests(filter: "Game") → 14/14 tests pass

You: "Add a Niagara fire effect to the torch actor" Agent calls: 1. get_level_actors(name_filter: "Torch") → finds actor path 2. lookup_class("UNiagaraComponent") → checks API 3. niagara_ops(operation: "spawn_system", system_path: "/Game/FX/NS_Fire", ...) 4. niagara_ops(operation: "set_parameter", parameter_name: "SpawnRate", value: 50)

You: "Create a PCG scatter for placing rocks on the landscape" Agent calls: 1. lookup_docs("PCG scatter landscape") → reads PCG docs 2. pcg_ops(operation: "list_components") → finds existing PCG actors 3. spawn_actor(class: "Actor", name: "RockScatter") 4. pcg_ops(operation: "add_node", node_type: "SurfaceSampler") 5. pcg_ops(operation: "execute") → generates rocks

# Build make build # Run all tests with race detector make test # Go lint make lint # C++ format check (requires clang-format) make cpp-fmt-check # Run all checks (Go format, C++ format, vet, lint, tests) make check

# Build the test project (first run ~2-5 min, incremental after) make test-cpp-build # Build and run all MCPUnreal. automation tests make test-cpp

SeeCONTRIBUTING.mdfor development setup, coding standards, and how to add new tools.

Cyber Host Artificial Intelligence (C.H.A.I) is Autonomous penetration testing MCP (Model Context Protocol) server with an integrated AI decision engine, multi-provider LLM support, and an extensible plugin architecture.