Unreal Python

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

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