funplay-unreal-mcp

<p align="center"> <h1 align="center">Funplay MCP for Unreal</h1> <p align="center"><strong>The most advanced MCP server for the Unreal Editor.</strong></p> <p align="center"> <img src="https://img.shields.io/badge/Unreal%20Engine-5.3%E2%80%935.8-blue" alt="Unreal Engine 5.3-5.8" /> <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT" /> <img src="https://img.shields.io/badge/MCP-compatible-purple" alt="MCP compatible" /> <img src="https://img.shields.io/badge/editor-only-lightgrey" alt="Editor only" /> </p> <p align="center"><a href="./README_CN.md">中文</a> | English</p> </p> > 💖 If this saves you time, please star the repo — it helps a lot. --- Funplay MCP for Unreal lets AI assistants — **Claude Code, Cursor, Windsurf, Codex, VS Code Copilot** and any other MCP client — operate directly inside a running Unreal Editor. It is a **pure-Python editor plugin** (no C++ build, works across Unreal Engine 5.3–5.8) that exposes the editor over a local MCP server, plus a tiny Node.js stdio bridge that connects your AI client to it. MIT-licensed and free for commercial use. Describe what you want in natural language — *spawn and arrange actors, build levels and Blueprints, create materials, import assets, drive Play-In-Editor, capture screenshots, or run arbitrary `execute_python`* — and let the assistant do it. > "Build a small arena: a floor, four walls, some point lights, and a player > start in the middle. Then play it and send me a screenshot." > > The assistant inspects the level, spawns and positions the actors, sets up > lighting, enters Play-In-Editor, and returns a screenshot — all through this > MCP server. ## Demo <p align="center"> <img src="./docs/assets/codex-to-unreal-castle-demo.gif" alt="Codex uses Funplay MCP to build a castle in Unreal Editor" width="900" /> </p> Codex asks for a castle, Funplay MCP drives the Unreal Editor through MCP, and the finished scene appears directly in the editor. ## Quick Start Three things: **(1)** drop the plugin into your project, **(2)** enable it and start the server, **(3)** point your AI client at it. ### 1. Install the plugin > 💡 The plugin is pure Python — there is nothing to compile. - Copy the `FunplayMCP/` folder into your project's `Plugins/` directory (`<YourProject>/Plugins/FunplayMCP/`), **or** download `Funplay.UnrealMcp.vX.Y.Z.zip` from the latest [Release](https://github.com/FunplayAI/funplay-unreal-mcp/releases) and extract it there. - It depends on the engine's **Python Editor Script Plugin**, which the `.uplugin` enables automatically. ### 2. Enable and start the MCP Server - Open your project. In **Edit → Plugins**, confirm **Funplay MCP for Unreal** is enabled, then restart the editor if prompted. - On startup the server listens at `http://127.0.0.1:8765/` by default. If the port is busy it automatically picks a free local port (and a second editor of the *same* project attaches to the existing server). - A per-project **auth token** is generated and stored in `<YourProject>/Saved/FunplayMCP/funplay_mcp_settings.json`. - Get the endpoint and token any time from **Tools → Funplay MCP → Log Endpoint + Token** (printed to the Output Log). ### 3. Configure your AI client The fastest path is the editor menu: **Tools → Funplay MCP → Configure Claude Code** (or Cursor / VS Code / Codex). It writes the right config with the endpoint and token filled in. <details> <summary>Manual configuration</summary> **Claude Code** (`~/.claude.json`), **Cursor** (`~/.cursor/mcp.json`): ```json { "mcpServers": { "funplay-unreal": { "command": "npx", "args": ["-y", "funplay-unreal-mcp"], "env": { "FUNPLAY_UNREAL_MCP_URL": "http://127.0.0.1:8765/", "FUNPLAY_UNREAL_MCP_TOKEN": "<token from the Funplay MCP menu>" } } } } ``` **VS Code** (`mcp.json`) uses the `servers` key; **Codex** (`~/.codex/config.toml`) uses a `[mcp_servers."funplay-unreal"]` table. Both are written for you by the one-click menu. </details> ### 4. Verify the connection Ask your assistant to: - call `get_project_info`, - read the resource `unreal://project/context`, - run `execute_python` with `result = unreal.SystemLibrary.get_engine_version()`. ## Before You Start - **Editor only.** The server runs inside the Unreal Editor; it does not ship in packaged games. - **Loopback only.** It binds `127.0.0.1` and rejects non-loopback Origins; POST requests require the per-project auth token. - **Default `core` profile.** A focused 32-tool set is exposed by default; switch to `full` (97 tools) in the settings file when you want everything. - **`execute_python` safety checks** are on by default (a filesystem/process denylist); pass `safety_checks=false` to override per call. - All `unreal` API work is marshalled onto the game thread, so the editor never crashes from off-thread access. ## Why This Project - **`execute_python` first.** A first-class tool that runs arbitrary Python in the editor — anything the 96 dedicated tools don't cover, you can still do. - **API discovery built in.** `search_api` / `describe_class` / `inspect_object` read the embedded `unreal` module's own docs, so the assistant uses the real API instead of hallucinating it. - **Pure Python, no build.** No C++ module, no compile step, portable across UE 5.3–5.8. - **Safe by construction.** Game-thread marshalling, loopback binding, auth token, and DNS-rebinding protection out of the box. - **One-click client config + project skills.** Configure Claude Code / Cursor / VS Code / Codex and generate an `AGENTS.md` bridge from the editor menu. - **Same family, same conventions** as Funplay MCP for Unity / Godot / Cocos. ## Highlights - **97 built-in tools** (32 in the default `core` profile) across 20 categories. - **MCP resources** (`unreal://...`) for project, level, selection, logs, and the tool catalog, plus **prompt templates** for common workflows. - **Structured results** — every tool returns JSON the assistant can reason over; screenshots come back as inline images. - **Auto port-fallback** and **same-project instance attach**. - **Zero-dependency Node bridge** published to npm as `funplay-unreal-mcp`. ## MCP Capabilities - **Tools:** 97 (32 core / 97 full). - **Primary execution:** `execute_python` — run any Python snippet in the editor. - **Prompts:** `level_review`, `feature_plan`, `debug_runtime`, `blueprint_actor`. - **Resources:** `unreal://project/context`, `unreal://project/info`, `unreal://level/current`, `unreal://actors/list`, `unreal://selection/current`, `unreal://tools/catalog`, `unreal://logs/recent`, `unreal://interaction/history`, plus templates `unreal://actor/{ref}` and `unreal://asset/{path}`. ## Comparison with Funplay MCP for Unity | | Funplay MCP for Unreal | Funplay MCP for Unity | |---|---|---| | Editor side | Pure-Python plugin (no build) | C# package | | Primary execution | `execute_python` (embedded `unreal`) | `execute_code` (in-memory C#) | | Transport | Local HTTP + stdio bridge | Local HTTP + stdio bridge | | Default exposure | `core` profile (32 of 97) | `core` profile | | Engine versions | UE 5.3–5.8 | Unity 2022.3+ | | Client config | One-click (Claude/Cursor/VS Code/Codex) | One-click | ## Built-in Tools **97 built-in tools** (32 `core`). Call `get_tool_catalog` for the live list. | Category | Tools | |---|---| | Execution | `execute_python`, `run_console_command` | | Reflection | `search_api`, `describe_class`, `list_enum_values`, `inspect_object` | | Actors | `spawn_actor`, `spawn_actor_from_asset`, `destroy_actor`, `duplicate_actor`, `set_actor_transform`, `set_actor_label`, `set_actor_property`, `attach_actor`, `get_actor_info`, `list_actors`, `find_actors`, `batch_spawn_actors` | | Components | `add_component`, `list_components`, `get_component_properties`, `set_component_property`, `set_static_mesh`, `set_material`, `set_physics_properties`, `add_ism_instances` | | Assets | `list_assets`, `find_assets`, `get_asset_info`, `duplicate_asset`, `rename_asset`, `delete_asset`, `save_asset`, `import_asset`, `create_folder`, `asset_exists`, `get_asset_references` | | Blueprints | `create_blueprint`, `add_blueprint_component`, `compile_blueprint`, `get_blueprint_info`, `spawn_blueprint` | | Materials | `create_material`, `create_material_instance`, `set_material_instance_parameter`, `get_material_info`, `add_material_expression`, `connect_material_expressions`, `connect_material_property`, `recompile_material` | | Levels | `new_level`, `load_level`, `save_current_level`, `save_all_dirty`, `get_level_info`, `list_levels` | | Play-In-Editor | `play_in_editor`, `stop_play_in_editor`, `simulate_in_editor`, `get_play_state` | | Viewport | `set_viewport_camera`, `get_viewport_camera`, `focus_viewport` | | Screenshots | `take_screenshot` | | Selection | `get_selection`, `set_selection`, `select_none`, `get_selected_assets` | | Editor State | `get_editor_state`, `get_project_info`, `get_output_log`, `sync_content_browser`, `health_status`, `undo`, `redo` | | Files | `read_file`, `write_file`, `list_directory`, `file_exists` | | Procedural | `build_wall`, `build_floor`, `build_stairs`, `scatter_actors` | | Organization | `set_actor_folder`, `create_layer`, `add_actors_to_layer`, `list_layers` | | Data | `create_data_table`, `get_data_table`, `set_data_table_rows`, `export_data_table_csv` | | UMG | `create_widget_blueprint`, `add_widget`, `set_widget_property` | | Effects | `spawn_niagara_system`, `set_niagara_parameter` | | Discovery | `get_tool_catalog` | ## Repository Layout ``` FunplayMCP/ # the Unreal editor plugin (pure Python) FunplayMCP.uplugin Content/Python/ init_unreal.py # auto-run entry point funplay_mcp/ # server, transport, registry, providers tools/ # one module per tool category stdio-wrapper/ # zero-dependency Node.js stdio<->HTTP bridge scripts/ # validate_repo.py, package_release.py tests/ # Node + Python tests (run without the editor) server.json # MCP registry manifest ``` ## Architecture ``` AI client (Claude Code / Cursor / ...) │ stdio (MCP JSON-RPC) ▼ funplay-unreal-mcp (Node bridge, npx) │ HTTP + token → 127.0.0.1:8765 ▼ Unreal Editor plugin (Python) │ game-thread pump (register_slate_post_tick_callback) ▼ unreal API → Actors / Assets / Blueprints / Levels / PIE ``` ## Contributing See [CONTRIBUTING.md](./CONTRIBUTING.md). Run `python3 scripts/validate_repo.py` before opening a PR. ## License MIT — see [LICENSE](./LICENSE).