Skip to main content
Glama

unreal-python-mcp

MCP (Model Context Protocol) server for Unreal Python API documentation and execution.

Enables AI coding assistants like Claude Code to:

  • Browse Unreal Python API documentation

  • Search for classes and functions

  • Execute Python code in Unreal Editor

Installation

# Clone the repository
git clone https://github.com/self-taught-code-tokushima/unreal-python-mcp.git
cd unreal-python-mcp

# Install with uv
uv sync

Related MCP server: VERA MCP Server

Claude Code Setup

Add to your Claude Code MCP configuration (~/.config/claude/mcp.json or project-level .mcp.json):

{
  "mcpServers": {
    "unreal-python": {
      "command": "uv",
      "args": ["--directory", "D:\\UnrealProjects\\unreal-python-mcp", "run", "unreal-python-mcp"]
    }
  }
}

or

{
  "mcpServers": {
    "unreal-python": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/self-taught-code-tokushima/unreal-python-mcp", "unreal-python-mcp"]
    }
  }
}

Requirements

  • Python 3.13+

  • Unreal Editor with Python plugin enabled

  • "Enable Remote Execution" checked in Editor Preferences > Plugins > Python

Custom Modules Support

In addition to the built-in unreal module, you can document custom Python modules available in your Unreal Editor environment (e.g., MaterialGraphEditor).

Setup

Add the env section to your MCP configuration with the UNREAL_PYTHON_CUSTOM_MODULES environment variable:

{
  "mcpServers": {
    "unreal-python": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/self-taught-code-tokushima/unreal-python-mcp", "unreal-python-mcp"],
      "env": {
        "UNREAL_PYTHON_CUSTOM_MODULES": "YourCustomModule1,YourCustomModule2"
      }
    }
  }
}

Refreshing Cache with Custom Modules

After configuring custom modules, refresh the cache to include them:

# Windows PowerShell
$env:UNREAL_PYTHON_CUSTOM_MODULES="MaterialGraphEditor,BlueprintGraphEditor"
uvx unreal-python-mcp-refresh

# Or with uv run
$env:UNREAL_PYTHON_CUSTOM_MODULES="MaterialGraphEditor,BlueprintGraphEditor"
uv run unreal-python-mcp-refresh
# Linux/macOS
UNREAL_PYTHON_CUSTOM_MODULES="MaterialGraphEditor,BlueprintGraphEditor" uvx unreal-python-mcp-refresh

Notes

  • Specify multiple modules as comma-separated values

  • Custom modules will appear in the module list alongside built-in modules

  • The MCP server will automatically use the configured modules when it starts

Available Tools

Tool

Description

search_unreal_api

Search API by class/function name

get_class_overview

Get class overview (member name lists, 1-3KB)

get_member_info

Get detailed info for a specific member

get_members_info

Get detailed info for multiple members (batch)

list_modules

List available Unreal modules

exec_unreal_python

Execute Python code in Unreal Editor

list_unreal_instances

List available Unreal Editor instances

refresh_api_cache

Refresh API documentation cache (also available as CLI: uvx unreal-python-mcp-refresh)

Available Resources

Hierarchical Index

Classes are organized by module to minimize context usage.

Resource

Size

Description

unreal-python://index/summary

~2KB

Start here. API overview with module list

unreal-python://index/module/{name}

~20-90KB

Classes for a specific module

unreal-python://index/enums

~50KB

All enums

unreal-python://index/structs

~200KB

All structs

unreal-python://index/delegates

~10KB

All delegates

Common modules:

  • Engine (994 classes): Core classes - Actor, World, GameplayStatics

  • UnrealEd (204 classes): Editor utilities - EditorAssetLibrary

  • UMG (110 classes): UI/Widget classes

  • Niagara (98 classes): Particle system

Class Documentation

Resource

Description

unreal-python://class/{name}

Detailed class documentation

Usage Example

In Claude Code:

User: Actor クラスの位置を取得するメソッドを教えて

Claude: [Reads unreal-python://index/summary]
        → Engine モジュールに Actor があることを確認

        [Reads unreal-python://index/module/Engine]
        → Actor: 145 methods, 48 properties

        [Uses get_class_overview("Actor")]
        → メソッド名一覧を取得(1-2KB程度)

        [Uses get_member_info("Actor", "get_actor_location")]
        → 詳細ドキュメントを取得

        Actor の位置を取得するには get_actor_location() を使います。
        返り値は Vector 型です。
User: EditorAssetLibrary の使い方を教えて

Claude: [Reads unreal-python://index/summary]
        → UnrealEd モジュールにあることを確認

        [Reads unreal-python://index/module/UnrealEd]
        [Uses get_class_overview("EditorAssetLibrary")]
        → メソッド名一覧を取得

        EditorAssetLibrary はエディタ専用のアセット操作ユーティリティです...
User: Unreal で Hello World を出力して

Claude: [Uses exec_unreal_python("print('Hello World')")]

        実行結果: Hello World

First-time Setup

  1. Start Unreal Editor with a project

  2. Enable Python Remote Execution in Editor Preferences (Editor Preferences > Plugins > Python > Enable Remote Execution)

  3. Refresh the API documentation cache:

# Using uvx (recommended)
uvx unreal-python-mcp-refresh

# Or with uv run (if you cloned the repository)
uv run unreal-python-mcp-refresh

Alternatively, you can use the refresh_api_cache MCP tool from Claude Code after connecting to the MCP server.

Development

# Run MCP dev server (with inspector)
uv run mcp dev src/unreal_python_mcp/server.py

# Run directly
uv run unreal-python-mcp

License

MIT

Available Tools

8 tools
exec_unreal_pythonA

Execute Python code in the running Unreal Editor.

Requires Unreal Editor to be running with Python Remote Execution enabled. Check Editor Preferences > Plugins > Python > Enable Remote Execution.

Args: code: Python code to execute in Unreal Editor

Inputs: code (required). Returns: result

get_class_overviewA

Get class overview with member name lists only (very lightweight).

By default, returns only member NAMES without docstrings (fetched from TOC, no Unreal query). Set include_doc=True to also fetch class docstring and base classes from Unreal.

Use get_member_info or get_members_info to get details for specific members.

This is much more efficient than fetching full documentation - especially for large classes like Actor which would be 100KB+ with full details.

Args: class_name: The exact class name (e.g., "Actor", "EditorAssetLibrary") include_doc: If True, also fetch class docstring and bases (default: False)

Inputs: class_name (required), include_doc. Returns: result

get_member_infoA

Get detailed documentation for a specific member of a class.

Returns the member type (method/property/constant), docstring, signature (for methods), and value (for constants).

Args: class_name: The class name (e.g., "Actor") member_name: The member name (e.g., "get_actor_location")

Inputs: class_name (required), member_name (required). Returns: result

get_members_infoA

Get detailed documentation for multiple members at once (batch operation).

More efficient than calling get_member_info multiple times when you need details for several members.

Args: class_name: The class name (e.g., "Actor") member_names: List of member names (e.g., ["get_actor_location", "set_actor_location"])

Inputs: class_name (required), member_names (required). Returns: result

list_modulesA

List all available Unreal modules with class counts.

Use this to discover what modules are available, then use unreal-python://index/module/{name} resource to get classes for that module.

Inputs: no named parameters. Returns: result

list_unreal_instancesA

List all running Unreal Editor instances with Remote Execution enabled.

Use this to check if Unreal Editor is available for code execution.

Inputs: no named parameters. Returns: result

refresh_api_cacheA

Refresh the Unreal Python API documentation cache.

This fetches the latest API documentation from a running Unreal Editor and updates the local cache. Requires Unreal Editor to be running.

Inputs: no named parameters. Returns: result

search_unreal_apiA

Search Unreal Python API by class or function name.

Returns matching entries from the API index. Use this to find the correct class/function name before getting detailed documentation.

Args: query: Search query (supports partial matching and regex)

Inputs: query (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.5/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool serves a clearly distinct purpose: checking editor availability, searching the API, getting class overviews, fetching member details (single vs batch), executing Python, listing modules, and refreshing the cache. Even the two member-lookup tools are obviously differentiated by batch vs single operation.

    Naming Consistency5/5

    All tool names follow a consistent snake_case verb_noun pattern (e.g., list_unreal_instances, search_unreal_api, exec_unreal_python). The verbs are specific and predictable, making it easy to guess what each tool does.

    Tool Count5/5

    With 8 tools, the server is well-scoped for its purpose. It provides just enough surface area to cover discovery, documentation lookup, and code execution without unnecessary bloat or redundancy.

    Completeness5/5

    The tool set covers the full workflow for Unreal Python API exploration and execution: check if an editor is available, search for API symbols, inspect modules/classes/members, get detailed documentation, execute code, and refresh the API cache. There are no obvious missing operations that would leave an agent stuck.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to interact with Unreal Editor 5 through the Python remote execution protocol. It allows for managing the editor lifecycle, configuring project settings, and executing Python scripts directly within the Unreal Engine environment.
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Exposes the Unreal Editor for Fortnite to AI assistants via MCP, enabling actor manipulation, device property editing, Verse building, and more through a Python bridge.
      3
      GPL 3.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to directly control and interact with the Unreal Editor through natural language, allowing tasks such as spawning actors, building levels, creating materials, and running Python scripts.
      11
      MIT