convez.ai
MCP ServerProdutividadeAvançado
elliotttate

Unreal Asset MCP

elliotttate/unreal-asset-mcp

Inspecionar assets Unreal Engine via agentes de IA sem abrir o Editor

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que oferece acesso profundo e somente leitura a projetos Unreal Engine sem abrir o Editor. Analisa binários `.uasset` e `.umap` diretamente, constrói um índice SQLite pesquisável e expõe ferramentas para buscas e inspeção de assets (Blueprints, Materials, Levels, AnimBlueprints, etc).

Instalação

$npx convez-ai elliotttate/unreal-asset-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
1
Acompanhando
0
Saúde
57%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Buscar assets específicos em projetos Unreal grandes
  • Analisar estrutura de Blueprints, Materials e Levels via IA
  • Auditar e documentar conteúdo de projetos Unreal automaticamente

Veredito

Ferramenta especializada de altíssimo valor para equipes Unreal que usam agentes de IA. Resgata informações estruturais complexas de assets binários sem overhead do Editor, mas exige .NET 8.0+ e conhecimento técnico sólido de Unreal.

README

A tradução para o português deste README ainda está na fila.

Unreal Asset MCP

Tests License: MIT

An MCP server that gives AI coding agents deep, read-only access to an Unreal Engine project without launching the Editor. It parses .uasset / .umap binaries directly, builds a searchable SQLite index of your whole project, and exposes two tools over MCP — unreal_search and inspect_asset.

Ask your agent things like:

  • "Which levels have an ExponentialHeightFog actor?"
  • "Which post-process materials read the WorldNormal scene texture?"
  • "Show me the full node graph of M_Glass — what feeds Opacity?"
  • "Find every Blueprint that contains a StereoLayerComponent."
  • "What states are in ABP_Enemy's locomotion state machine?"

What it can inspect

Asset typeWhat you get
BlueprintParent class, components (with class names), functions, variables, event/function graphs, decompiled bytecode
WidgetBlueprintWidget tree hierarchy, bindings, animations
MaterialDomain / blend mode / shading model, parameters, full expression node graph with wired pins (detail="graph"), SceneTexture usage, Custom HLSL nodes
MaterialInstanceParent chain, overridden parameters, static switches, inherited domain/blend/shading resolved through the parent chain
MaterialFunctionInputs/outputs and full node graph
Level / World (.umap)Actors grouped by class, detailed rendering/lighting actors (PostProcessVolumes, fog, lights, reflection captures, WorldSettings), level-script functions
ParticleSystem / NiagaraSystemEmitters, modules, renderers
AnimBlueprintState machines (states + transitions), anim node usage, referenced animations
DataTableRow structure, columns, row data
C++ source (optional)UCLASS/UPROPERTY/UFUNCTION bridge so searches connect Blueprints to their native parents

Mixed-version content is handled: projects migrated from UE4 that contain both 4.x-era and 5.x-era serialized assets parse correctly (the bundled UAssetAPI is patched for this — see Bundled UAssetAPI).

Requirements

  • .NET SDK 8.0+ (10.0 recommended — the bundled UAssetAPI multi-targets net8.0;net10.0)
  • Python 3.10+

Installation

git clone https://github.com/elliotttate/unreal-asset-mcp
cd unreal-asset-mcp
python -m venv .venv
source .venv/bin/activate  # macOS/Linux
# .venv\Scripts\activate   # Windows
pip install -e .

This installs two CLI entry points:

  • unreal-asset-toolkit — index management
  • unreal-asset-mcp — MCP server

Optional dependencies

pip install -e ".[embeddings]"  # vector embeddings (sentence-transformers)
pip install -e ".[dev]"         # pytest + coverage

Quick Start

# 1. Build the parser and register your project
python setup.py /path/to/YourProject.uproject

# 2. Build the search index (include plugin content)
unreal-asset-toolkit --plugins

# 3. Connect your MCP client (see below)

setup.py builds the C# parser, installs Python packages, and registers your .uproject. Add --index to combine steps 1 and 2.

MCP Client Setup

Register the server in your MCP client config:

{
  "mcpServers": {
    "unreal": {
      "command": "unreal-asset-mcp"
    }
  }
}

If you didn't pip install -e ., use the full Python path instead:

{
  "mcpServers": {
    "unreal": {
      "command": "/path/to/.venv/bin/python",
      "args": ["/path/to/unreal-asset-mcp/unreal_asset_mcp/mcp_server.py"]
    }
  }
}

See mcp-config.example.json for a copy-paste template.

MCP Tools

unreal_search

Search assets and C++ source. The mode is auto-detected from the query:

QueryMode
"BP_Player"Exact name match
"player health widget"Semantic / full-text search
"levels with ExponentialHeightFog"Level-content search
"where is BP_Enemy used"Reference search
"inherits:GameplayAbility"Inheritance search
"tag:Ability.Melee.*"GameplayTag search

inspect_asset

Structured data for one asset. Useful detail levels:

  • summary (default) — type-appropriate overview
  • graph — for Materials/MaterialFunctions/MaterialInstances: the full expression graph as nodes + edges with pin names and root output bindings; for Blueprints: event/function graphs
  • bytecode — decompiled Blueprint bytecode

Indexing

unreal-asset-toolkit                        # full index (default)
unreal-asset-toolkit --plugins              # include plugin content
unreal-asset-toolkit --plugins --embed      # + vector embeddings
unreal-asset-toolkit --source               # C++ source pass (UCLASS, UPROPERTY)
unreal-asset-toolkit --profile quick        # high-value types only
unreal-asset-toolkit --path UI              # only Content/UI/
unreal-asset-toolkit --force                # re-index everything
unreal-asset-toolkit --status               # show index stats

The index is two-tier: semantically rich asset types (Blueprints, Widgets, Materials, DataTables, Levels…) get full-text documents; everything else (textures, meshes, sounds) gets a lightweight path + reference entry. Material instances additionally get their effective domain/blend/shading resolved through their parent chain after each run, so a search for "post process material" also finds instances.

Project profiles

Type detection uses standard naming conventions (BP_, WBP_, DT_, M_/MI_…). If your project uses non-standard prefixes, add a profile in unreal_asset_mcp/profiles/<project>.json and reference it from your project entry in config.json:

{
  "name_prefixes": {
    "PP_": "Material",
    "PPI_": "MaterialInstance",
    "WGT_": "WidgetBlueprint"
  }
}

Multi-Project Setup

unreal-asset-toolkit add "/path/to/MyGame.uproject"
unreal-asset-toolkit list
unreal-asset-toolkit use mygame

Each project gets an isolated SQLite database at unreal_asset_mcp/data/<project>.db.

Architecture

MCP Client (Claude Code, Claude Desktop, etc.)
        │
        ▼
MCP Server (Python, stdio)
├── unreal_search  →  SQLite FTS5 index (+ optional vector embeddings)
└── inspect_asset  →  C# AssetParser  →  .uasset / .umap binaries

The C# parser reads asset binaries directly via the bundled UAssetAPI. The Python layer classifies assets, batches them through the parser, builds the FTS5 index, and serves results over MCP.

Bundled UAssetAPI

UAssetAPI/ contains a patched copy of atenfyr/UAssetAPI (MIT). Patches on top of upstream:

  • Mixed UE4/UE5 projects: versioned UE4-era packages no longer inherit a forced UE5 object version, fixing parse failures in projects that migrated from 4.x and still contain old-format assets.
  • Material input serialization: FColorMaterialInput constants read as FLinearColor post-MaterialInputUsesLinearColor; FVector(2)MaterialInput constants read as explicit floats (never LWC doubles); added ShadingModelMaterialInput / SubstrateMaterialInput. Without these, UE5-saved materials' MaterialEditorOnlyData fails to parse and the node graph is unavailable.
  • Asset-registry resilience: malformed editor-only asset-registry tag maps no longer abort the whole package parse (the data is recovered as null and parsing continues).

Known Limitations

  • Read-only — cannot modify assets
  • Niagara — emitter/module names are indexed, but user-parameter values are not
  • AnimBlueprints — state machines are extracted; blend-tree wiring inside states is not

Credits & License

MIT — see LICENSE.

This project builds on UE-Agent-Asset-Toolkit by Braden League (MIT) and bundles a patched UAssetAPI by atenfyr (MIT — see UAssetAPI/LICENSE).

Ver o original no GitHub

Bom para

Relacionados