Funplay Unreal MCP

💖 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

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 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.

Claude Code (~/.claude.json), Cursor (~/.cursor/mcp.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.

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

Built-in Tools

97 built-in tools (32 core). Call get_tool_catalog for the live list.

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. Run python3 scripts/validate_repo.py before opening a PR.

License

MIT — see LICENSE.