Unreal Asset MCP
elliotttate/unreal-asset-mcp
Inspecionar assets Unreal Engine via agentes de IA sem abrir o Editor
Ver no GitHubServidor 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-mcp1 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
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
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 type | What you get |
|---|---|
| Blueprint | Parent class, components (with class names), functions, variables, event/function graphs, decompiled bytecode |
| WidgetBlueprint | Widget tree hierarchy, bindings, animations |
| Material | Domain / blend mode / shading model, parameters, full expression node graph with wired pins (detail="graph"), SceneTexture usage, Custom HLSL nodes |
| MaterialInstance | Parent chain, overridden parameters, static switches, inherited domain/blend/shading resolved through the parent chain |
| MaterialFunction | Inputs/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 / NiagaraSystem | Emitters, modules, renderers |
| AnimBlueprint | State machines (states + transitions), anim node usage, referenced animations |
| DataTable | Row 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 managementunreal-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:
| Query | Mode |
|---|---|
"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 overviewgraph— for Materials/MaterialFunctions/MaterialInstances: the full expression graph as nodes + edges with pin names and root output bindings; for Blueprints: event/function graphsbytecode— 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:
FColorMaterialInputconstants read asFLinearColorpost-MaterialInputUsesLinearColor;FVector(2)MaterialInputconstants read as explicit floats (never LWC doubles); addedShadingModelMaterialInput/SubstrateMaterialInput. Without these, UE5-saved materials'MaterialEditorOnlyDatafails 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).