UnrealEngineMCP
# Unreal Engine MCP
[](https://github.com/axcel-blade/UE-MCP/actions/workflows/ci.yml)
[](https://github.com/axcel-blade/UE-MCP/actions/workflows/cd.yml)
[](https://github.com/axcel-blade/UE-MCP/actions/workflows/pages.yml)
[](https://github.com/axcel-blade/UE-MCP/actions/workflows/release.yml)
[](https://github.com/axcel-blade/UE-MCP/releases/latest)
[](LICENSE)
[](https://www.python.org/)
[](https://docs.astral.sh/uv/)
[](https://www.unrealengine.com/)
[](docs/ARCHITECTURE.md)
[](SECURITY.md)
Production-oriented **Model Context Protocol (MCP)** integration for **Unreal Engine 5**. AI clients (Claude Desktop, Cursor, VS Code, Codex, Windsurf, and others) can inspect projects, spawn and edit actors, manage levels/assets/Blueprints, capture viewports, and automate Editor workflows through a local bridge.
This project is **not** affiliated with Epic Games.
## Features
- MCP stdio server + Unreal Editor C++ plugin TCP bridge (localhost by default)
- Length-prefixed JSON protocol with GameThread-safe execution
- Actor, level, asset, Blueprint, material, lighting, and viewport tools
- Scene intelligence helpers and high-level workflows (`unreal_create_room`, `unreal_setup_lighting`, …)
- Safe / Advanced security modes; destructive actions require confirmation
- Optional bridge auth token; Blender→Unreal FBX import validation helpers
- uv-based Python toolchain with CI, CD, Pages, and Release GitHub Actions
See [docs/IMPLEMENTATION_STATUS.md](docs/IMPLEMENTATION_STATUS.md) for honest coverage of implemented vs `unsupported` tools.
## Prerequisites
- [uv](https://docs.astral.sh/uv/) (required)
- Python 3.11+
- Unreal Engine 5.3+ with **Editor Scripting Utilities**
- Windows 10/11 (primary); Visual Studio 2022 or Rider to compile the plugin
## Quick start
Install site (Astro / GitHub Pages): [axcel-blade.github.io/UE-MCP](https://axcel-blade.github.io/UE-MCP/)
**Windows (PowerShell)** — one liner:
```powershell
irm https://axcel-blade.github.io/UE-MCP/install.ps1 | iex
```
**macOS / Linux:**
```bash
curl -LsSf https://axcel-blade.github.io/UE-MCP/install.sh | sh
```
Or from a local clone with uv:
```powershell
uv sync
uv run python scripts/install_plugin.py --project "D:\Path\To\YourProject.uproject"
```
1. Open the Unreal project → enable **Unreal Engine MCP** (+ Editor Scripting Utilities) → compile / restart
2. Confirm Output Log: bridge listening on `127.0.0.1:55557`
3. Point your MCP client at:
```json
{
"mcpServers": {
"unreal-engine-mcp": {
"command": "uv",
"args": [
"run",
"--directory",
"C:/path/to/UE-MCP",
"unreal-engine-mcp"
],
"env": {
"UNREAL_ENGINE_MCP_HOST": "127.0.0.1",
"UNREAL_ENGINE_MCP_PORT": "55557",
"UNREAL_ENGINE_MCP_SECURITY_MODE": "safe"
}
}
}
}
```
Smoke test:
```powershell
uv run python scripts/test_connection.py
```
More client samples: [config/mcp_clients/](config/mcp_clients/). Full install guide: [docs/INSTALLATION.md](docs/INSTALLATION.md).
## Documentation
| Document | Purpose |
|----------|---------|
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | System design |
| [docs/INSTALLATION.md](docs/INSTALLATION.md) | Install & MCP client setup |
| [docs/CONFIGURATION.md](docs/CONFIGURATION.md) | Config & environment |
| [docs/GETTING_STARTED.md](docs/GETTING_STARTED.md) | First workflow |
| [docs/COMMUNICATION_PROTOCOL.md](docs/COMMUNICATION_PROTOCOL.md) | Wire protocol |
| [docs/MCP_TOOLS.md](docs/MCP_TOOLS.md) | MCP tools overview |
| [docs/MCP_RESOURCES.md](docs/MCP_RESOURCES.md) | MCP resources |
| [docs/MCP_PROMPTS.md](docs/MCP_PROMPTS.md) | MCP prompts |
| [docs/SECURITY_MODEL.md](docs/SECURITY_MODEL.md) | Safe / Advanced mode controls |
| [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) | Common failures |
| [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) | Developer guide |
| [docs/TESTING.md](docs/TESTING.md) | Test strategy |
| [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md) | Engine / client compatibility |
| [docs/GIT_FLOW.md](docs/GIT_FLOW.md) | Branching model |
| [docs/DECISIONS.md](docs/DECISIONS.md) | Engineering decision log |
| [docs/IMPLEMENTATION_STATUS.md](docs/IMPLEMENTATION_STATUS.md) | Feature status |
| [CHANGELOG.md](CHANGELOG.md) | Version history |
| [CONTRIBUTING.md](CONTRIBUTING.md) | Git Flow & contribution guide |
| [SUPPORT.md](SUPPORT.md) | How to get help |
| [SECURITY.md](SECURITY.md) | Vulnerability reporting |
| [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) | Community standards |
| [LICENSE](LICENSE) | MIT license |
## Architecture
```text
AI Client --stdio MCP--> unreal-engine-mcp --TCP length-prefixed JSON--> Unreal Engine MCP plugin --Editor APIs--> Unreal Engine
```
See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
Architectural reference: [Blender-MCP](https://github.com/axcel-blade/Blender-MCP) (patterns adapted for Unreal; not a code copy). Also evaluated: IvanMurzak/Unreal-MCP, flopperam/unreal-engine-mcp, tahooki/unreal-blender-mcp.
## Git Flow
| Branch | Purpose |
|--------|---------|
| `main` | Production releases |
| `develop` | Integration |
| `feature/*` | Features → `develop` |
| `release/*` | Release prep → `main` + `develop` |
| `hotfix/*` | Urgent fixes from `main` |
Details: [CONTRIBUTING.md](CONTRIBUTING.md) · [docs/GIT_FLOW.md](docs/GIT_FLOW.md).
### CI / CD / Pages / Release
| Workflow | When | What |
|----------|------|------|
| [CI](.github/workflows/ci.yml) | Push/PR on Git Flow branches | uv lint, pytest (3.11–3.13), plugin layout check |
| [Pages](.github/workflows/pages.yml) | Push to `develop`/`main` touching `site/**`, or manual | Build Astro site and deploy GitHub Pages |
| [Release](.github/workflows/release.yml) | Manual dispatch (from `main`) | Version bump, CHANGELOG, tag `v*`, GitHub Release, dispatch CD |
| [CD](.github/workflows/cd.yml) | Tag `v*` / Release dispatch | Build wheels, pack plugin zip, attach assets, optional PyPI, refresh Pages |
`main` and `develop` are branch-protected (PR + review). Details: [docs/GIT_FLOW.md](docs/GIT_FLOW.md).
## Security
- Bridge binds to `127.0.0.1` by default
- Optional shared auth token
- Default **Safe** mode restricts script/console execution and gates destructive tools with `confirmed=true`
- `unreal_execute_editor_python` / console commands require Advanced mode + explicit config flags — they are **not a sandbox**
Report vulnerabilities privately via [SECURITY.md](SECURITY.md). Product controls: [docs/SECURITY_MODEL.md](docs/SECURITY_MODEL.md).
## Development
This project is managed exclusively with **uv** (lockfile + virtualenv).
```powershell
uv sync
uv run pytest
uv run ruff check mcp_server tests scripts
uv run unreal-engine-mcp
```
Diagnose a live Unreal connection:
```powershell
uv run python scripts/diagnose.py
uv run python scripts/test_connection.py
```
Plugin sources: `UnrealEngineMCP/Source/UnrealEngineMCP/`.
## License
MIT © AXCEL BLADE — see [LICENSE](LICENSE).
Unreal® is a trademark of Epic Games, Inc. This project is not affiliated with or endorsed by Epic Games.
TDQS
Scored across 225 tools
The set spans many resources, but boundaries are blurred by numerous overlapping inspection/settings/save operations such as get_render_settings vs get_rendering_settings, get_status vs get_editor_status vs ping, and save_all vs per-asset saves. Actor transform editing is also split across composite and granular tools. With 225 tools, an agent must choose among many similar-sounding tools, increasing misselection risk.
Nearly all tools use the unreal_ prefix and snake_case, usually following a verb_noun pattern like unreal_create_blueprint or unreal_get_asset_info. Minor exceptions such as unreal_engine_mcp_version and unreal_job_status break the verb-first pattern, but overall naming is predictable.
225 tools is far beyond the well-scoped 3-15 range and exceeds the 50+ extreme threshold. While the surface is broad, the monolith size makes reliable tool discovery and selection impractical.
Core CRUD/lifecycle coverage exists for actors, assets, levels, Blueprints, materials, animation, Niagara, widgets, sequences, physics, diagnostics, and project settings. Coverage is broad, though some Unreal domains such as landscape/foliage, audio, and deeper AI/blackboard editing appear absent or read-only, leaving minor gaps.