{
  "markdown": "# Unreal Engine MCP Server\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![NPM Package](https://img.shields.io/npm/v/unreal-engine-mcp-server)](https://www.npmjs.com/package/unreal-engine-mcp-server)\n[![MCP SDK](https://img.shields.io/badge/MCP%20SDK-TypeScript-blue)](https://github.com/modelcontextprotocol/sdk)\n[![Unreal Engine](https://img.shields.io/badge/Unreal%20Engine-5.0--5.8-orange)](https://www.unrealengine.com/)\n[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-Published-green)](https://registry.modelcontextprotocol.io/)\n[![Project Board](https://img.shields.io/badge/Project-Roadmap-blueviolet?logo=github)](https://github.com/users/ChiR24/projects/3)\n[![Discussions](https://img.shields.io/badge/Discussions-Join-brightgreen?logo=github)](https://github.com/ChiR24/Unreal_mcp/discussions)\n\nA comprehensive Model Context Protocol (MCP) server that enables AI assistants to control Unreal Engine through a native C++ Automation Bridge plugin. Built with TypeScript and C++.\n\n---\n\n## Table of Contents\n\n- [Features](#features)\n- [Getting Started](#getting-started)\n- [Configuration](#configuration)\n- [Available Tools](#available-tools)\n- [Docker](#docker)\n- [Documentation](#documentation)\n- [Community](#community)\n- [Development](#development)\n- [Contributing](#contributing)\n\n---\n\n## Features\n\n| Category | Capabilities |\n|----------|-------------|\n| **Asset Management** | Browse, import, duplicate, rename, delete assets; create materials |\n| **Actor Control** | Spawn, delete, transform, physics, tags, components |\n| **Editor Control** | PIE sessions, camera, viewport, screenshots, bookmarks |\n| **Level Management** | Load/save levels, streaming, lighting |\n| **Animation & Physics** | Animation BPs, state machines, ragdolls, vehicles, constraints |\n| **Visual Effects** | Niagara particles, GPU simulations, procedural effects, debug shapes |\n| **Sequencer** | Cinematics, timeline control, Movie Render Queue, media, Take Recorder, replay |\n| **Graph Editing** | Blueprint, Niagara, Material, and Behavior Tree graph manipulation |\n| **Audio** | Sound cues, audio components, sound mixes, ambient sounds |\n| **System** | Console commands, UBT, tests, logs, project settings, CVars |\n\n### Architecture\n\n- **Native C++ Automation** — All operations route through the MCP Automation Bridge plugin\n- **Dual Transport** — Native HTTP/SSE (no bridge needed) or WebSocket via TypeScript bridge\n- **Dynamic Type Discovery** — Runtime introspection for lights, debug shapes, and sequencer tracks\n- **Graceful Degradation** — Server starts even without an active Unreal connection\n- **On-Demand Connection** — Retries automation handshakes with exponential backoff\n- **Command Safety** — Blocks dangerous console commands with pattern-based validation\n- **Capability Token Auth** — On-by-default token authentication (auto-generated 32-byte secret at `<Project>/Saved/MCP/capability-token`) for both WS and HTTP transports; manual `CapabilityToken` in Project Settings overrides the file\n- **Asset Caching** — 10-second TTL for improved performance\n- **Metrics Rate Limiting** — Per-IP rate limiting (60 req/min) on Prometheus endpoint\n- **Centralized Configuration** — Unified class aliases and type definitions\n\n---\n\n## Getting Started\n\n### Prerequisites\n\n- **Node.js 20.19 or later** (Node.js 18 is not supported) — required for the TypeScript stdio bridge. Not needed for the native MCP transport.\n\n### Step 1: Install MCP Server (Option B only — skip for Native MCP)\n\n> Skip this step if using **Option A: Native MCP Transport** ([Step 4A](#option-a-native-mcp-transport-direct-http--no-bridge-needed) below).\n\n**NPX (Recommended):**\n```bash\nnpx unreal-engine-mcp-server\n```\n\n**Clone & Build:**\n```bash\ngit clone https://github.com/ChiR24/Unreal_mcp.git\ncd Unreal_mcp\nnpm install\nnpm run build\nnode dist/cli.js\n```\n\n### Step 2: Install Unreal Plugin\n\nThe MCP Automation Bridge plugin is included at `Unreal_mcp/plugins/McpAutomationBridge`.\n\n#### From source (requires a project with code target)\n\nYour project must have a code target (`.sln` or `.xcworkspace`).\nBlueprint-only projects cannot compile native plugins — to convert, add any class via **Tools > New C++ Class** in the editor.\n\n**Method 1: Copy Folder**\n```text\nCopy:  Unreal_mcp/plugins/McpAutomationBridge/\nTo:    YourUnrealProject/Plugins/McpAutomationBridge/\n```\n\n**Method 2: External Plugin Directory (no copy needed)**\n1. Open Unreal Editor → **Edit → Plugins**\n2. Click **Plugin Directories** (bottom-left)\n3. In **Additional Plugin Directories**, add the path to `Unreal_mcp/plugins/`\n4. Restart the editor — the plugin will be picked up from the external location\n\nThis saves the path in your `.uproject` file so the plugin stays linked without copying.\n\nThe plugin compiles automatically when you open the project — UE detects the `.uplugin` + `Source/` and runs UnrealBuildTool.\n\n**Video Guide:**\n\nhttps://github.com/user-attachments/assets/d8b86ebc-4364-48c9-9781-de854bf3ef7d\n\n> ⚠️ **First-Time Project Open:** UE may prompt *\"Would you like to rebuild them now?\"* — click **Yes**. If instead you see *\"Missing Modules — McpAutomationBridge. Engine modules cannot be compiled at runtime. Please build through your IDE.\"* — open your project in **Visual Studio** (Win) or **Xcode** (Mac) and build from there. After that, the editor will open normally with the plugin loaded.\n\n#### Pre-built (works with any project, including Blueprint-only)\n\nBuild the plugin once, then distribute the compiled binaries — no IDE or compilation needed on the target machine.\n\n**1. Build:**\n```bash\n# macOS / Linux\n./scripts/package-plugin.sh /path/to/UE_5.6\n\n# Windows\nscripts\\package-plugin.bat C:\\Path\\To\\UE_5.6\n```\n\nThis produces a zip like `McpAutomationBridge-v0.5.30-UE5.7-Linux.zip`.\n\n**2. Install:** unzip into `YourProject/Plugins/` and open the project. That's it — no compilation step.\n\n> Note: pre-built binaries are tied to a specific UE version. A build for 5.6 won't work with 5.5, 5.7, or 5.8.\n\n### Step 3: Enable Required Plugins\n\nEnable via **Edit → Plugins**, then restart the editor.\n\n<details>\n<summary><b>Core Plugins (Required)</b></summary>\n\n| Plugin | Required For |\n|--------|--------------|\n| **MCP Automation Bridge** | All automation operations |\n| **Python Editor Script Plugin** | Python-backed editor automation helpers |\n| **Editor Scripting Utilities** | Asset/Actor subsystem operations |\n| **Niagara** | Visual effects and particle systems |\n| **Gameplay Abilities** | `manage_gas` operations |\n| **Smart Objects** | AI smart object operations |\n\n</details>\n\n<details>\n<summary><b>Optional Plugins (Auto-enabled)</b></summary>\n\n| Plugin | Required For |\n|--------|--------------|\n| **Level Sequence Editor** | `manage_sequence` operations |\n| **Movie Render Pipeline** | `manage_sequence` Movie Render Queue operations |\n| **Movie Pipeline Mask Render Pass** | Object-ID render pass |\n| **Takes** | `manage_sequence` Take Recorder operations |\n| **Electra Player** | `manage_sequence` file-backed media playback |\n| **Control Rig** | `animation_physics` operations |\n| **GeometryScripting** | `manage_geometry` operations |\n| **Behavior Tree Editor** | `manage_ai` Behavior Tree operations |\n| **Niagara Editor** | Niagara authoring |\n| **Environment Query Editor** | AI/EQS operations |\n| **MetaSound** | `manage_audio` MetaSound authoring |\n| **StateTree** | `manage_ai` State Tree operations |\n| **Enhanced Input** | `manage_networking` input mapping operations |\n| **Chaos Cloth** | Cloth simulation |\n| **Interchange** | Asset import/export |\n| **Data Validation** | Data validation |\n| **PCG** | `manage_pcg` graph authoring and execution when enabled for the build |\n| **Procedural Mesh Component** | Procedural geometry |\n| **OnlineSubsystem** | Session/networking operations |\n| **OnlineSubsystemUtils** | Session/networking operations |\n\n</details>\n\n> 💡 Optional plugins are auto-enabled by the MCP Automation Bridge plugin when needed.\n> PCG support is compiled for source projects when the project explicitly enables PCG. Versioned release packages for UE 5.2+ include PCG support. All Unreal Engine versions from 5.0 to 5.8 are supported and working.\n\n### Step 4: Configure MCP Client\n\n#### Option A: Native MCP Transport (Direct HTTP — no bridge needed)\n\nThe plugin includes a built-in MCP Streamable HTTP server. AI clients connect directly to the plugin over HTTP — no TypeScript bridge, no Node.js, no npm.\n**Note:** the `bAllowNonLoopback` setting now applies to **both** the WebSocket bridge and the native MCP transport. Enabling it binds both surfaces to non-loopback addresses. If you only need LAN access for the WebSocket bridge, do not enable `bAllowNonLoopback` and instead expose the bridge via a reverse proxy. Capability token auth is on by default (0.5.30+) — both transports require authentication automatically. A manually configured `CapabilityToken` in Project Settings or the auto-generated token at `<Project>/Saved/MCP/capability-token` is used automatically.\n\n**Enable in Unreal:**\n1. **Edit > Project Settings > Plugins > MCP Automation Bridge**\n2. Check **Enable Native MCP**\n3. Set port (default: `3000`)\n4. Optionally set **Native MCP Instructions** for project-specific guidance\n5. Restart the editor\n\n**Configure your MCP client** to use Streamable HTTP transport at:\n```\nhttp://localhost:3000/mcp\n```\n\n**Claude Code:**\n```bash\nclaude mcp add unreal-engine --transport http http://localhost:3000/mcp\n```\n\nOr manually in `~/.claude/settings.json` or project `.mcp.json`:\n```json\n{\n  \"mcpServers\": {\n    \"unreal-engine\": {\n      \"type\": \"url\",\n      \"url\": \"http://localhost:3000/mcp\"\n    }\n  }\n}\n```\n\n**Cursor** (`.cursor/mcp.json`):\n```json\n{\n  \"mcpServers\": {\n    \"unreal-engine\": {\n      \"url\": \"http://localhost:3000/mcp\"\n    }\n  }\n}\n```\n\n**Verify it works:**\n- **Status bar** — look for `● MCP :3000 (2)` in the bottom-right of the editor. Green dot = server running, number in parens = active sessions. Click it to open settings.\n- **Output Log** — filter by `LogMcpNativeTransport` to see connections, tool calls, and session activity:\n  ```\n  LogMcpNativeTransport: Native MCP server started on http://localhost:3000/mcp\n  LogMcpNativeTransport: MCP session initialized: ... (client: claude-code 2.1.92, active sessions: 1)\n  LogMcpNativeTransport: tools/call: inspect (RequestId=...)\n  LogMcpNativeTransport: tools/call completed: ... (tool=inspect, success=true)\n  ```\n\nFeatures:\n- SSE streaming for real-time progress during long operations\n- Multiple concurrent sessions (Cursor + Claude Code + others simultaneously)\n- Dynamic tool management — core tools load by default, enable more via `manage_tools`\n- Python execution via `execute_python` action (inline code or .py files)\n- Capability token authentication — on by default (auto-generated secret at `<Project>/Saved/MCP/capability-token`; manual `CapabilityToken` in Project Settings overrides)\n\n#### Option B: TypeScript Bridge (stdio — classic setup)\n\nAdd to your Claude Desktop / Cursor config file:\n\n**Using Clone/Build:**\n```json\n{\n  \"mcpServers\": {\n    \"unreal-engine\": {\n      \"command\": \"node\",\n      \"args\": [\"path/to/Unreal_mcp/dist/cli.js\"],\n      \"env\": {\n        \"UE_PROJECT_PATH\": \"C:/Path/To/YourProject\",\n        \"MCP_AUTOMATION_PORT\": \"8091\"\n      }\n    }\n  }\n}\n```\n\n**Using NPX:**\n```json\n{\n  \"mcpServers\": {\n    \"unreal-engine\": {\n      \"command\": \"npx\",\n      \"args\": [\"unreal-engine-mcp-server\"],\n      \"env\": {\n        \"UE_PROJECT_PATH\": \"C:/Path/To/YourProject\"\n      }\n    }\n  }\n}\n```\n\n---\n\n## Configuration\n\n### Environment Variables\n\n```env\n# Required\nUE_PROJECT_PATH=\"C:/Path/To/YourProject\"\n\n# Automation Bridge\nMCP_AUTOMATION_HOST=127.0.0.1\nMCP_AUTOMATION_PORT=8091\n\n# LAN Access (optional)\n# SECURITY: Set to true to allow binding to non-loopback addresses (e.g., 0.0.0.0)\n# Only enable if you understand the security implications.\nMCP_AUTOMATION_ALLOW_NON_LOOPBACK=false\n\n# Logging\nLOG_LEVEL=info  # debug | info | warn | error\n\n# Optional\nMCP_CONNECTION_TIMEOUT_MS=5000\nMCP_REQUEST_TIMEOUT_MS=120000\nASSET_LIST_TTL_MS=10000\n\n# Optional Prometheus metrics endpoint\n# Loopback-only by default. Non-loopback metrics requires both explicit opt-in and a token.\n# MCP_METRICS_PORT=9100\n# MCP_METRICS_HOST=127.0.0.1\n# MCP_METRICS_ALLOW_NON_LOOPBACK=false\n# MCP_METRICS_TOKEN=change-me\n\n# Custom content mount points (comma-separated)\n# Plugins with CanContainContent register mount points beyond /Game/.\n# MCP_ADDITIONAL_PATH_PREFIXES=/ProjectObject/,/ProjectAnimation/\n```\n\n### LAN Access Configuration\n\nBy default, the automation bridge only binds to loopback addresses (127.0.0.1) for security. To enable access from other machines on your network:\n\n**TypeScript (MCP Server):**\n```env\nMCP_AUTOMATION_ALLOW_NON_LOOPBACK=true\nMCP_AUTOMATION_HOST=0.0.0.0\n```\n\n**Unreal Engine Plugin:**\n1. Go to **Edit → Project Settings → Plugins → MCP Automation Bridge**\n2. Under **Security**, enable **\"Allow Non Loopback\"**\n3. Under **Connection**, set **\"Listen Host\"** to `0.0.0.0`\n4. Restart the editor\n\n⚠️ **Security Warning:** Enabling LAN access exposes the automation bridge to your local network. Only use on trusted networks with appropriate firewall rules. **Enable capability token authentication** (`Require Capability Token` in project settings) to prevent unauthorized access when using LAN mode.\n\n---\n\n## Available Tools\n\nThe MCP server exposes a single **`unreal`** gateway tool. The 23 canonical parent tools are internal and reachable exclusively through the gateway's four operations: `search`, `describe`, `execute`, and `configure`.\n\n### Gateway Workflow\n\n1. **`search`** — discover available tools by keyword, category, or action name\n2. **`describe`** — get the exact contract (actions, parameters, schema) for a specific tool\n3. **`execute`** — run one validated action on a canonical tool\n4. **`configure`** — manage internal tool enable/disable state (wraps `manage_tools`)\n\nExample call:\n\n```json\n{\n  \"operation\": \"search\",\n  \"query\": \"asset\"\n}\n```\n\nThen:\n\n```json\n{\n  \"operation\": \"describe\",\n  \"tool\": \"manage_asset\",\n  \"action\": \"import_asset\"\n}\n```\n\nThen:\n\n```json\n{\n  \"operation\": \"execute\",\n  \"tool\": \"manage_asset\",\n  \"action\": \"import_asset\",\n  \"params\": { \"sourcePath\": \"/path/to/asset.fbx\", \"destinationPath\": \"/Game/Imported/asset\" }\n}\n```\n\n### Migration from direct tool calls\n\nThe single `unreal` gateway is permanent on both transports; there is no opt-out and no legacy 23-tool listing to restore. A client that still calls a canonical tool name directly (`tools/call` with `name: \"manage_asset\"`, `name: \"control_actor\"`, etc.) receives a bounded, copy-paste-executable `DIRECT_TOOL_CALL_REMOVED` receipt instead of a routed call. The receipt carries a `nextCall` that drills exactly one level: `{ \"operation\": \"search\" }` for an unknown name, `{ \"operation\": \"describe\", \"tool\": \"<tool>\" }` when no action was supplied, or `{ \"operation\": \"execute\", \"tool\": \"<tool>\", \"action\": \"<action>\", \"params\": { ... } }` when the direct call already named an action. Run that `nextCall` through the `unreal` tool to finish the migration.\n\n### Gateway Protocol & Transport\n\nBoth transports expose the same `unreal` gateway contract, but they are separate lifecycles. Do not route around their boundaries.\n\n- **TypeScript stdio transport** — `node dist/cli.js` talks to the Unreal plugin over a WebSocket bridge. It permanently exposes the single `unreal` gateway tool; there is no gateway-mode toggle.\n- **Native MCP transport** — the plugin's built-in Streamable HTTP/SSE server at `/mcp` (no Node.js, no bridge). The native MCP surface permanently exposes the same single `unreal` gateway tool; there is no gateway-mode toggle.\n\nBoth surfaces negotiate the MCP protocol version at `initialize`; the supported set is intentionally asymmetric. The native `/mcp` transport supports exactly the three modern versions `2025-11-25`, `2025-06-18`, and `2025-03-26`, and deliberately does not implement the later `2026-07-28` RC. The TypeScript stdio server also accepts the two legacy versions `2024-11-05` and `2024-10-07`, so the native surface is intentionally stricter. Both negotiate down to the highest mutually supported version (`2025-11-25` is the latest). See [docs/protocol.md](docs/protocol.md) for the full negotiation and transport contract, including the `MCP-Protocol-Version` header guard (HTTP 400 on invalid), cancellation semantics, and `progressToken` handling.\n\n### Internal Canonical Tools (23)\n\nThe gateway hides these 23 canonical parent tools. They are listed here for reference:\n\n<details>\n<summary><b>Core Tools</b></summary>\n\n| Tool | Description |\n|------|-------------|\n| `manage_asset` | Assets, Materials, Render Targets, Behavior Trees, Blueprint Struct (UserDefinedStruct) authoring |\n| `manage_blueprint` | Blueprints, SCS components, graph editing, UMG widgets, layout, bindings, animations |\n| `control_actor` | Spawn, delete, transform, physics, tags |\n| `control_editor` | PIE, Camera, viewport, screenshots |\n| `manage_level` | Load/save, streaming, lighting |\n| `system_control` | UBT, Tests, Logs, Project Settings, CVars, Python Execution |\n| `inspect` | Object Introspection |\n| `manage_tools` | Dynamic tool management (enable/disable at runtime) |\n\n</details>\n\n<details>\n<summary><b>World Building</b></summary>\n\n| Tool | Description |\n|------|-------------|\n| `build_environment` | Landscapes, foliage, procedural terrain, lighting, spline roads/rivers/fences |\n| `manage_level_structure` | Levels, sublevels, World Partition, streaming, data layers, HLOD, volumes |\n| `manage_geometry` | Procedural mesh creation and editing with Geometry Script |\n| `manage_pcg` | PCG graph assets, subgraphs, input/sampler/filter/spawner nodes, pin connections, execution, partition grid size, and node settings |\n\n</details>\n\n<details>\n<summary><b>Gameplay Systems</b></summary>\n\n| Tool | Description |\n|------|-------------|\n| `animation_physics` | Animation BPs, skeletons, sockets, physics assets, cloth, vehicles, ragdolls, Control Rig, IK |\n| `manage_effect` | Niagara, particles, debug shapes, GPU simulations |\n| `manage_gas` | Gameplay Ability System: abilities, effects, attributes |\n| `manage_character` | Character creation, movement, advanced locomotion |\n| `manage_combat` | Weapons, projectiles, damage, melee combat |\n| `manage_ai` | AI controllers, Behavior Trees, EQS, perception, State Trees, Smart Objects, NavMesh/pathfinding |\n| `manage_inventory` | Items, equipment, loot tables, crafting |\n| `manage_interaction` | Interactables, destructibles, triggers |\n\n</details>\n\n<details>\n<summary><b>Utility</b></summary>\n\n| Tool | Description |\n|------|-------------|\n| `manage_audio` | Audio Assets, Components, Sound Cues, MetaSounds, Attenuation |\n| `manage_sequence` | Sequencer, cinematics, Movie Render Queue, media playback, Take Recorder, and replay controls |\n| `manage_networking` | Replication, RPCs, network prediction, sessions, split-screen, LAN/voice, game framework, input mappings |\n\n</details>\n### Supported Asset Types\n\nBlueprints • Materials • Textures • Static Meshes • Skeletal Meshes • Levels • Sounds • Particles • Niagara Systems • Behavior Trees\n\n---\n\n## Docker\n\n```bash\ndocker build -t unreal-mcp .\ndocker run -it --rm -e UE_PROJECT_PATH=/project unreal-mcp\n```\n\n---\n\n## Documentation\n\n| Document | Description |\n|----------|-------------|\n| [Handler Mappings](docs/handler-mapping.md) | TypeScript to C++ routing |\n| [Plugin Extension](docs/editor-plugin-extension.md) | C++ plugin architecture |\n| [Testing Guide](docs/testing-guide.md) | How to run and write tests |\n| [Roadmap](docs/Roadmap.md) | Development roadmap |\n\n\n---\n\n## Development\n\n```bash\nnpm run build         # Clean + compile TypeScript to dist/\nnpm run lint          # Run ESLint 9 (fail on any warning)\nnpm run type-check    # tsc --noEmit\nnpm run test:unit     # Vitest unit tests (no Unreal required)\nnpm run test:smoke    # Offline mock in-memory MCP check (needs built dist/)\nnpm run manifest:check   # Fail if generated gateway manifest artifacts drift\nnpm run test:native-parity # TS vs native canonical tool/action equality\nnpm run test:params      # Parity + strict parameter audit\nnpm run version:check    # Assert all version sources agree\nnpm test                 # Integration suite (needs a live Unreal Editor + bridge)\n```\n\n### Gateway manifest generation\n\nThe neutral gateway manifest is generated from `src/tools/catalog/consolidated-tool-definitions.ts` into three artifacts (runtime `.ts`/`.json` plus the native `.h`). Never hand-edit the generated files.\n\n```bash\nnode --loader ts-node/esm scripts/generate-gateway-manifest.ts          # regenerate\nnode --loader ts-node/esm scripts/generate-gateway-manifest.ts --check  # CI gate: fail on drift\n```\n\n### CI gates\n\nCI runs, in order: ESLint 9 (`npx eslint . --max-warnings=0`), TypeScript type-check, unit tests, `registry:check`, `normalization:check`, `manifest:check`, `policy:check`, native parity + parameter audit (`test:params`), `migration:check`, `primitives:check`, `security:check`, `eval:check`, `version:check`, `workflow:check`, then a blocking runtime-only dependency audit (`npm audit --omit=dev --audit-level=high`) followed by an informational full-tree `npm audit --audit-level=moderate`. A plugin packaging job runs `scripts/package-plugin.sh` only when an Unreal Engine source root secret is provided (opt-in), because CI runners do not ship an engine. Release archives exclude `Binaries/`, `Intermediate/`, and `Saved/` so generated build dirs never leak.\n\n---\n\n## Community\n\n| Resource | Description |\n|----------|-------------|\n| [Project Roadmap](https://github.com/users/ChiR24/projects/3) | Track roadmap progress and priorities |\n| [Discussions](https://github.com/ChiR24/Unreal_mcp/discussions) | Ask questions, share ideas, get help |\n| [Issues](https://github.com/ChiR24/Unreal_mcp/issues) | Report bugs and request features |\n\n---\n\n## Contributing\n\nContributions welcome! Please:\n- Include reproduction steps for bugs\n- Keep PRs focused and small\n- Follow existing code style\n\n---\n\n## License\n\nMIT — See [LICENSE](LICENSE)\n\n",
  "bytes": 22220,
  "sha": "db5bfc68e90b163265004471f250dc459de8cad486e777d843a86570ca07aa2e",
  "repo_slug": "chir24/unreal_mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_ai_smithery_chir24_unreal_mcp_645903ec/readme"
}