Core Plugins (Required)

\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

\n\n

Optional Plugins (Auto-enabled)

\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

\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 `/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 `/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\": \"\" }` when no action was supplied, or `{ \"operation\": \"execute\", \"tool\": \"\", \"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](https://github.com/ChiR24/Unreal_mcp/blob/dev/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

Core Tools

\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

\n\n

World Building

\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

\n\n

Gameplay Systems

\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

\n\n

Utility

\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

\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](https://github.com/ChiR24/Unreal_mcp/blob/dev/docs/handler-mapping.md) | TypeScript to C++ routing |\n| [Plugin Extension](https://github.com/ChiR24/Unreal_mcp/blob/dev/docs/editor-plugin-extension.md) | C++ plugin architecture |\n| [Testing Guide](https://github.com/ChiR24/Unreal_mcp/blob/dev/docs/testing-guide.md) | How to run and write tests |\n| [Roadmap](https://github.com/ChiR24/Unreal_mcp/blob/dev/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](https://github.com/ChiR24/Unreal_mcp/blob/dev/LICENSE)\n\n","changelogMarkdown","videoKey","requiredSecretsJson","publishedAt","priceCents","trialDays",0,"iconType","image","upstream",{"_99":100,"_101":102,"_103":104,"_105":106,"_107":-5,"_108":109},"requiredSecrets",[],"tags",[97,98],"assets",[],"stats",{"_95":82,"_96":82},"ratingAvg","reviewCount","unreal-engine","unreal-engine-5","topics",[110,111,97,98],"license","MIT","language","TypeScript","registryName","ai.smithery/ChiR24-unreal_mcp","homepage","packages",[],"mcp","mcp-server","ENV",{"_114":115,"_116":117,"_118":119},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272"]

Unreal mcp