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