# unreal-engine-mcp

A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that gives
AI agents (Claude Desktop/Code, Cursor, any MCP client) broad control over
**Unreal Engine 5.7** — spawning and editing actors, managing assets and levels,
creating Blueprints and materials, capturing screenshots, running headless builds
and automation tests, and executing arbitrary editor Python.

It is designed to reach **the whole engine**, not a fixed menu of features: a
small set of typed tools cover the common operations, and `search_unreal_classes`
+ `introspect_unreal_class` + `execute_python` let an agent discover and drive
anything else the `unreal` Python module exposes — including features added by
enabled plugins (Niagara, PCG, Landscape, Sequencer, Gameplay Ability System,
Chaos, MetaHuman, …).

> **Status:** functional reference implementation. The host-side code is tested
> and the server boots and registers all tools. The live-editor paths require a
> running UE 5.7 editor with the bridge installed — see [docs/SETUP.md](docs/SETUP.md).
> No interactive editor was available in the authoring environment, so live calls
> have not been smoke-tested end to end; treat the engine-side behaviour as
> "implemented against the documented API" rather than "verified on a running editor".

## Why this design

Unreal exposes three external control surfaces; this server uses all three:

| Surface | What it is | Used for |
| --- | --- | --- |
| **Remote Control API** (HTTP :30010) | Built-in plugin: REST routes to read/write properties and call `UFunction`s, including the Python library CDO. | Live editor control + the Python channel. |
| **Python (`unreal` module)** | Reflects ~everything exposed to Blueprints; grows as you enable plugins. | The universal capability layer, reached *through* Remote Control. |
| **`UnrealEditor-Cmd`** (headless) | Commandlets / automation in a short-lived process. | Builds, cooks, packaging, automation tests. |

The key idea: instead of compiling a bespoke C++ plugin, we drive the editor's
own Python interpreter over the Remote Control HTTP API, and ship a tiny **UE-side
Python bridge** (`ue_mcp_bridge`, pure `.py`) that returns structured JSON so
round-trips are reliable. **No C++ compilation required** — only built-in plugins.

See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full picture and
[docs/CAPABILITIES.md](docs/CAPABILITIES.md) for the complete map of what's
reachable.

## Quick start

1. **In Unreal (5.7):** enable the **Remote Control API** and **Python Editor
   Script Plugin** plugins, then restart the editor.
2. **Install the bridge:** copy `unreal_plugin/Content/Python/` into your
   project's `Content/Python/` folder (so `init_unreal.py` and `ue_mcp_bridge/`
   sit directly under it). Restart the editor; the Output Log should show
   `[ue_mcp_bridge] ready`.
3. **Install the server:**
   ```bash
   pip install -e .          # or: pip install -r requirements.txt
   cp .env.example .env      # then edit paths/ports
   ```
4. **Register with your MCP client.** For Claude Desktop, add to
   `claude_desktop_config.json`:
   ```json
   {
     "mcpServers": {
       "unreal": {
         "command": "unreal-mcp",
         "env": {
           "UE_PROJECT_PATH": "/path/to/MyProject/MyProject.uproject",
           "UE_ENGINE_PATH": "/path/to/UE_5.7"
         }
       }
     }
   }
   ```
   (Claude Code: `claude mcp add unreal -- unreal-mcp`.)
5. Ask your agent: *"Call editor_state"* to confirm the connection, then
   *"Spawn a cube at the origin and take a screenshot."*

## Tool catalogue (35 tools)

**Editor & connection** — `editor_state`, `run_console_command`, `save_all`
**Actors** — `list_actors`, `get_actor`, `spawn_actor`, `spawn_static_mesh`,
`set_actor_transform`, `set_actor_property`, `destroy_actor`
**Assets** — `list_assets`, `asset_exists`, `asset_info`, `import_asset`,
`duplicate_asset`, `rename_asset`, `save_asset`, `delete_asset`
**Levels** — `new_level`, `load_level`, `save_current_level`
**Materials / Blueprints** — `create_material`, `create_blueprint`, `compile_blueprint`
**Rendering** — `take_screenshot`, `build_lighting`
**Universal** — `execute_python`, `search_unreal_classes`, `introspect_unreal_class`
**Headless pipeline** — `run_automation_tests`, `run_python_file`, `cook_content`
**Raw Remote Control** — `rc_get_property`, `rc_set_property`, `rc_call_function`

## Safety

- `.env` (and credential files / keys) are gitignored; never commit secrets.
- `UE_MCP_ALLOW_WRITE=false` puts the server in read-only mode — mutating tools
  refuse to run. Useful for exploration or untrusted sessions.
- `execute_python` runs arbitrary code in your editor. Only connect MCP clients
  you trust.

## Development

```bash
pip install -e ".[dev]"
PYTHONPATH=src python -m pytest tests/ -q     # host-side tests
PYTHONPATH=src python -c "from unreal_mcp.server import build_server; build_server()"
```

## License

MIT — see [LICENSE](LICENSE).