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

- **Type:** MCP server
- **Install:** `agentstack add mcp-remiphilippe-mcp-unreal`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [remiphilippe](https://agentstack.voostack.com/s/remiphilippe)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [remiphilippe](https://github.com/remiphilippe)
- **Source:** https://github.com/remiphilippe/mcp-unreal

## Install

```sh
agentstack add mcp-remiphilippe-mcp-unreal
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# mcp-unreal

[](https://github.com/remiphilippe/mcp-unreal/actions/workflows/ci.yml)
[](https://go.dev)
[](LICENSE)

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

```bash
# 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

- **Go 1.25+** — [install](https://go.dev/dl/)
- **Unreal Engine 5.7** — for build/test tools and editor interaction
- **Remote Control API plugin** — enabled in UE (see [Enabling Remote Control API](#enabling-remote-control-api) below)
- **MCPUnreal editor plugin** — for advanced editor tools (see [plugin/README.md](plugin/README.md))

## Installation

### From Source

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

### Pre-built Binaries

Download from [GitHub Releases](https://github.com/remiphilippe/mcp-unreal/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:

```bash
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:

```bash
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](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:**

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

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

```json
{
  "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):

```json
{
  "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:**

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

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

```toml
[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):

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

### Windsurf

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

```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:

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

### Zed

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

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

```markdown
## 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       │
                                                    │                       │
                                                    │  ┌─────────────────┐  │
                                                    │  │ 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       │
                                                    └───────────────────────┘
```

Three communication paths:
1. **Headless** — `exec.Command` invokes `UnrealEditor-Cmd` for builds, tests, and cooking. No editor needed.
2. **Remote Control API** — HTTP PUT to `localhost:30010` for property access and function calls. Built into UE.
3. **MCPUnreal Plugin** — HTTP POST to `localhost:8090` for Blueprint editing, asset queries, mesh ops, and other deep editor internals.

See [IMPLEMENTATION.md](IMPLEMENTATION.md) for the full architecture document.

## Available Tools (48)

### Build & Compile (Headless)

| Tool | Description |
|------|-------------|
| `build_project` | Build the UE project via UnrealEditor-Cmd / UBT. Returns structured JSON with error count and error details. |
| `cook_project` | Cook (package) content for a target platform using RunUAT. Supports iterative cooks. |
| `generate_project_files` | Regenerate IDE project files (.xcworkspace / .sln) after adding or removing C++ modules. |

### Project & Config (Headless)

| Tool | Description |
|------|-------------|
| `project_ops` | Read and modify the .uproject file: get project info, list/enable/disable plugins, add modules, set target platforms. |
| `config_ops` | Read and write UE project .ini config files (DefaultEngine.ini, DefaultGame.ini, etc.): get, set, delete keys, list sections. |

### Test Automation (Headless)

| Tool | Description |
|------|-------------|
| `run_tests` | Run headless automation tests (-nullrhi) with per-test pass/fail results and failure details. |
| `run_visual_tests` | Run automation tests with GPU rendering enabled (no -nullrhi) for visual/rendering tests. |
| `list_tests` | List available automation test names matching a filter pattern. |
| `get_test_log` | Read raw UE log files with line limits, offsets, and keyword filtering. |

### Actors & Properties (Editor)

| Tool | Description |
|------|-------------|
| `get_level_actors` | List all actors in the current level with class, path, location, rotation, scale. |
| `spawn_actor` | Spawn an actor by class name at a given location/rotation/scale. |
| `delete_actors` | Delete one or more actors by object path or display name. |
| `move_actor` | Set location, rotation, and/or scale of an actor via RC API function calls (`K2_SetActorLocation`, `K2_SetActorRotation`, `SetActorScale3D`). |
| `get_property` | Read a property value from an actor via the Remote Control API. |
| `set_property` | Set a property value on an actor via the Remote Control API. |
| `call_function` | Call a function on an object via the Remote Control API. |

### Blueprint Editing (Editor)

| Tool | Description |
|------|-------------|
| `blueprint_query` | Query Blueprint structure: list all BPs, inspect a BP's variables/functions/graphs, get graph nodes and connections. |
| `blueprint_modify` | Modify Blueprints: create, add/remove variables, add/remove functions, add/delete nodes, connect/disconnect pins, set pin values, compile. |

### Animation Blueprint Editing (Editor)

| Tool | Description |
|------|-------------|
| `anim_blueprint_query` | Query AnimBP state machines and states: list state machines, inspect states/transitions/blend spaces. |
| `anim_blueprint_modify` | Modify AnimBPs: add/remove states, add/remove transitions, set blend spaces, set state animations, set transition rules, add notify states. |

### Assets (Editor)

| Tool | Description |
|------|-------------|
| `search_assets` | Search assets by class, path, name, or tag. Returns paginated results. |
| `get_asset_info` | Get detailed asset info including dependencies and referencers. |

### Materials (Editor)

| Tool | Description |
|------|-------------|
| `material_ops` | Material operations: create, create_instance, set_parameter, set_texture, get_parameters, list_parameters. |

### Characters & Input (Editor)

| Tool | Description |
|------|-------------|
| `character_config` | Character configuration: get_config, set_movement, set_capsule, set_mesh, set_camera, get_movement_modes. |
| `input_ops` | Enhanced Input operations: list_actions, list_contexts, add_action, remove_action, add_context, bind_action, unbind_action, get_bindings. |

### Procedural Content Generation (Editor)

| Tool | Descriptio

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [remiphilippe](https://github.com/remiphilippe)
- **Source:** [remiphilippe/mcp-unreal](https://github.com/remiphilippe/mcp-unreal)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** yes

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-remiphilippe-mcp-unreal
- Seller: https://agentstack.voostack.com/s/remiphilippe
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.