Unity Prefab Parser MCP Server
Parses Unity text-serialized .prefab, .unity, and .asset files, extracting Inspector-visible component data into clean YAML format, reducing token usage for LLM analysis.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Unity Prefab Parser MCP Server Parse the prefab at Assets/Enemies/BatPF.prefab"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Unity Prefab Parser MCP Server
An MCP (Model Context Protocol) server that parses Unity text-serialized .prefab, .unity, and .asset files and outputs only Inspector-visible data in a clean, hierarchical YAML format — reducing token usage by up to 96%.
Supports regular prefabs, prefab variants (shows overridden values grouped by GameObject and component), and scene files.
Works with any MCP-compatible AI client: Claude Desktop, OpenCode, VS Code Copilot, Cursor, Windsurf, Codex, and more.
Quick Start
git clone https://github.com/luckynee/unity-prefab-parser-mcp.git
cd unity-prefab-parser-mcp
npm install && npm run buildThen add to your AI client config (see Client Setup below).
Related MCP server: Unity MCP Server
Recommended Workflow
First time on a project
1. init_unity_project — scan .meta files, build GUID cache (once per project)
2. browse_unity_project — navigate folder tree to find the right subfolder
3. list_unity_assets — list assets in that folder (filter by type or name)
4. parse_unity_file — parse with preset: "compact" for token-efficient outputSubsequent sessions
Skip init_unity_project if .unity-mcp-cache.json exists and is less than 24h old. Go straight to browse_unity_project or list_unity_assets.
Example prompt
Initialize my Unity project at /path/to/MyGame, then show me all enemy prefabs.The AI will call init_unity_project → browse_unity_project → list_unity_assets → parse_unity_file automatically.
Tools
init_unity_project
Scans all .meta files in a Unity project and saves a GUID→asset name cache to .unity-mcp-cache.json. Run once per project. Subsequent parse calls load from cache automatically — zero rescan cost.
{
"projectPath": "/path/to/MyUnityProject",
"force": false
}projectPath— path to the Unity project root (the folder containingAssets/,ProjectSettings/)force— force rescan even if cache is fresh (default:false)
Returns: asset count, time taken, cache file location.
browse_unity_project
Navigate the Unity project folder tree with asset counts per folder. Use this to find the subfolder you want before calling list_unity_assets.
{
"projectPath": "/path/to/MyUnityProject",
"subPath": "Assets/Enemies",
"depth": 2
}Example output:
Assets/
├── Enemies/ (12 prefabs)
├── UI/ (8 prefabs, 3 assets)
│ ├── HUD/ (4 prefabs)
│ └── Menus/ (4 prefabs)
├── Levels/ (5 scenes)
└── ScriptableObjects/ (23 assets)list_unity_assets
List .prefab, .unity, and .asset files in a directory with absolute paths ready to paste into parse_unity_file.
{
"directory": "/path/to/MyUnityProject/Assets/Enemies",
"type": "prefab",
"search": "bat",
"recursive": true,
"limit": 50
}type—"prefab","unity","asset", or"all"(default:"all")search— case-insensitive name filter (e.g."enemy"returnsEnemyBat.prefab,EnemyWolf.prefab)recursive— search subfolders (default:true)limit— max results (default:50)
parse_unity_file
Parse a Unity text-serialized file and extract Inspector-visible component data as clean YAML.
{
"filePath": "/path/to/MyUnityProject/Assets/Enemies/BatPF.prefab",
"config": {
"preset": "compact"
}
}Presets:
Preset | Token reduction | Best for |
| ~93–96% | LLM analysis, comparisons |
| ~84% | When you need GUID comments |
| ~95% | Quick structural overview |
You can mix preset with overrides:
{ "preset": "compact", "includeDefaultValues": true }parse_unity_prefab (deprecated)
Alias for parse_unity_file. Still works for backward compatibility.
Client Setup
All clients use the same MCP server binary. Replace /path/to/unity-prefab-parser-mcp with your actual clone path.
Claude Desktop
Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"unity-prefab-parser": {
"command": "node",
"args": ["/path/to/unity-prefab-parser-mcp/dist/index.js"]
}
}
}OpenCode
Add to your opencode.json:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"unity-parser": {
"type": "local",
"command": ["node", "/path/to/unity-prefab-parser-mcp/dist/index.js"],
"enabled": true
}
}
}OpenCode users: copy the bundled skills and commands to your OpenCode config directory:
# Copy all three Unity skills
cp -r /path/to/unity-prefab-parser-mcp/skills/unity-asset-workflow ~/.config/opencode/skills/
cp -r /path/to/unity-prefab-parser-mcp/skills/unity-diff-workflow ~/.config/opencode/skills/
cp -r /path/to/unity-prefab-parser-mcp/skills/unity-scene-workflow ~/.config/opencode/skills/
# Copy all Unity slash commands
cp /path/to/unity-prefab-parser-mcp/commands/*.md ~/.config/opencode/commands/Then restart OpenCode. Skills appear in /skills, commands appear in /commands.
Skill | Purpose |
| General workflow — init, browse, list, parse |
| Compare prefabs, variants, scenes across versions |
| Navigate large |
Slash commands available after installing:
/unity-init [path]— initialize project cache/unity-browse [path]— browse project tree/unity-list [path] [type] [search]— list assets/unity-parse [path]— parse with compact preset/unity-diff [pathA] [pathB]— compare two prefabs or scenes/unity-scene [path]— token-efficient scene overview
VS Code (GitHub Copilot / MCP extension)
Add to .vscode/mcp.json in your workspace, or to VS Code user settings:
{
"mcpServers": {
"unity-prefab-parser": {
"command": "node",
"args": ["/path/to/unity-prefab-parser-mcp/dist/index.js"]
}
}
}The .github/copilot-instructions.md bundled in this repo is auto-read by Copilot when the repo is open — no extra config needed for workflow guidance.
Cursor / Windsurf
Add to your MCP settings (Settings → MCP → Add Server):
{
"unity-prefab-parser": {
"command": "node",
"args": ["/path/to/unity-prefab-parser-mcp/dist/index.js"]
}
}Codex / Claude Code (CLI agents)
The AGENTS.md file bundled in this repo is auto-read by Codex and Claude Code when they run in the project directory — no extra config needed. They will follow the init → browse → list → parse workflow automatically.
Unity Serialization Requirement
This server requires Unity's text serialization format. If a file is binary, the server will reject it with a clear error.
Enable text serialization: Edit → Project Settings → Editor → Asset Serialization → Mode = Force Text
Example Output
Regular Prefab (compact mode)
prefab_name: BatPF
hierarchy: |
BatPF (t: Player, l: Layer28)
├── Geometry
└── Data
components:
BatPF:
Transform:
lPos: (27.13, -6.38, 0)
Rigidbody2D:
mass: 3
linearDrag: 5
angularDrag: 6
gravity: 0
bodyType: 0
sleepingMode: 1
CircleCollider2D: {trigger: true, radius: 0.5}
Data:
EntityData:
_entityName: Bat
_walkSpeed: 1.5
_attack: 10
_defense: 2
_isAlive: truePrefab Variant (compact mode)
Variants show variant_of and only the modifications from the base prefab, grouped by GameObject and actual component/script type:
prefab_name: Buck
variant_of: Buck Base
hierarchy: |
Buck Base # $
├── AI # $
├── Hitable Geometry # $
└── Unknown # $
components:
Buck Base:
Transform: # $
lPos: (-42.633396, -215.17801, 0) # $
GameObject: # $
name: Buck # $
Seeker: # $
tagPenalties.array.data: 10000 # $
AI:
AIBrain: # $
states.array.size: 7 # $
states.array.data.stateName: Exit Scene # $
states.array.data.transitions.array.array.data.trueState: Flee # $
Hitable Geometry:
GameObject: # $
layer: 20 # $
Unknown:
AggressiveAnimalData: # $
_defense: 3 # $
Animator: # $
ctrl: Buck Anim Controller # $Variant markers:
Marker | Meaning |
| Modified from base |
| Added (new component or GameObject) |
| Removed from base |
Note:
UnknownGameObjects are modification targets that live 2+ levels deep in nested prefab chains — their names can't be resolved without recursive loading.
Token Cost Reference
Real measurements on production prefabs:
File | Raw YAML | Parsed compact | Reduction |
Buck.prefab (variant, 38KB) | ~9,600 tokens | ~400 tokens | 96% |
Buck Base.prefab (full, 73KB) | ~18,000 tokens | ~1,200 tokens | 93% |
Operation costs:
Operation | Approx tokens |
| 0 (disk only) |
| ~200–500 |
| ~800 |
| ~150–1,200 |
| ~300–2,000 |
Raw Unity YAML (same file) | ~5,000–50,000 |
Configuration Reference
Option | Type | Default | Description |
|
| — | Use a preset |
| boolean |
| Resolve GUIDs to asset names |
| boolean |
| Show asset type as comment |
| number |
| Max array elements before summarizing |
| number |
| Max depth for nested objects |
| boolean |
| Include Transform components |
| boolean |
| Include disabled GameObjects |
| boolean |
| Include properties with default values |
| boolean |
| Include null/empty references |
| boolean |
| Include hierarchy section |
| string[] |
| Only include these component types |
| string[] |
| Exclude these component types |
| boolean |
| Convert 0/1 to true/false |
| boolean |
| Convert LayerMask to layer arrays |
| boolean |
| Use tree format for hierarchy |
| boolean |
| Shorten field names ( |
| boolean |
| Omit default position/rotation/scale |
| boolean |
| Use |
| boolean |
| Use |
| boolean |
| Inline components with 1–2 fields |
| boolean |
| Show |
Supported Components
Built-in field filters for:
Transform, RectTransform
Rigidbody, Rigidbody2D
All Collider types (Box, Sphere, Capsule, Circle, Polygon, Mesh)
SpriteRenderer, MeshRenderer, SkinnedMeshRenderer, MeshFilter
Animator, Animation
AudioSource, Camera, Light
Canvas, CanvasScaler, GraphicRaycaster
UI: Image, Text, TextMeshProUGUI, Button
ParticleSystem, ParticleSystemRenderer, TrailRenderer, LineRenderer
MonoBehaviour (custom scripts — all serialized fields shown)
Project Structure
unity-prefab-parser-mcp/
├── src/
│ ├── index.ts # MCP server, all tool definitions
│ ├── parser.ts # Unity YAML parsing
│ ├── resolver.ts # Reference and value resolution
│ ├── components.ts # Component field filters and renames
│ ├── hierarchy.ts # GameObject tree builder
│ ├── formatter.ts # YAML output formatter
│ ├── config.ts # Configuration and presets
│ ├── cache.ts # Meta file GUID cache
│ └── variant.ts # Prefab variant detection
├── skills/
│ ├── unity-asset-workflow/
│ │ └── SKILL.md # General workflow (init, browse, list, parse)
│ ├── unity-diff-workflow/
│ │ └── SKILL.md # Compare prefabs, variants, scenes
│ └── unity-scene-workflow/
│ └── SKILL.md # Navigate large scenes token-efficiently
├── commands/
│ ├── unity-init.md # /unity-init [path]
│ ├── unity-browse.md # /unity-browse [path]
│ ├── unity-list.md # /unity-list [path] [type] [search]
│ ├── unity-parse.md # /unity-parse [path]
│ ├── unity-diff.md # /unity-diff [pathA] [pathB]
│ └── unity-scene.md # /unity-scene [path]
├── test/
│ └── parser.test.ts # Test suite (103 tests)
├── AGENTS.md # Auto-read by Codex and Claude Code
├── .github/
│ └── copilot-instructions.md # Auto-read by GitHub Copilot
├── package.json
└── tsconfig.jsonDevelopment
npm install # install dependencies
npm run build # compile TypeScript
npm test # run test suite (103 tests)
npm run dev # run with tsx (no build needed)License
MIT
Available Tools
5 toolsbrowse_unity_projectA
Browse the Unity project folder tree with asset counts. Use this to navigate large projects and find the subfolder containing the assets you want to work with.
WORKFLOW:
init_unity_project (once)
browse_unity_project (navigate to the right folder)
list_unity_assets (list assets in that folder)
parse_unity_file (parse specific assets)
Inputs: projectPath (required), depth, subPath.
init_unity_projectA
Initialize a Unity project for use with this MCP. Scans all .meta files to build a GUID→asset name cache, enabling full asset name resolution in parse_unity_file.
WORKFLOW: Call this ONCE per project before using parse_unity_file or browse_unity_project. The cache is saved to .unity-mcp-cache.json in the project root and reused automatically.
For large projects (100GB+), this may take 10-30 seconds but only needs to run once per session or when assets change significantly.
Inputs: projectPath (required), force.
list_unity_assetsA
Scan a directory for Unity asset files (.prefab, .unity, .asset) and return a grouped list with absolute paths ready to use with parse_unity_file.
Inputs: type, exact, limit, search, +2 more.
parse_unity_fileA
Parse a Unity text-serialized prefab, scene, or asset file and extract Inspector-visible component data in YAML format.
WORKFLOW: For best results with asset name resolution, call init_unity_project first. If already initialized, the cache is loaded automatically.
Automatically resolves asset names from GUIDs by scanning the project's .meta files (or using the initialized cache). Outputs a clean, hierarchical structure showing the GameObject tree and all component data.
IMPORTANT: Fields not shown in output have their default values or are null references.
Transform: lPos (0,0,0), lRot (0,0,0,1), lScale (1,1,1) are omitted when default
Null references and unresolved GUIDs are omitted
enabled:true is omitted (only enabled:false is shown)
Features:
Resolves script, material, sprite, and other asset references to human-readable names
Filters out Unity internal fields (m_ObjectHideFlags, serializedVersion, etc.)
Renames fields to match Unity Inspector names (m_LocalPosition -> localPosition)
Supports configurable detail levels: minimal, standard, or compact
Prefab Variant Support:
Auto-detects prefab variants and nested prefab instances
Shows variant_of field with base prefab name
Groups all modifications under base prefab name
Merges Vector3 properties (x, y, z -> single vector)
Filters default values and null references
Adds # + markers for variant modifications
Compact mode optimizations (83% token reduction):
Short reference syntax (@Player instead of GameObject:Player)
Parentheses vector notation: (1, 2, 3) instead of {x:1, y:2, z:3}
Field abbreviations: lPos, lRot, lScale, trigger, order, mats
Inline simple components: {value: 42, active: true}
Omits null/Unknown references entirely
Omits enabled:true, default offsets, flipX/flipY:false
Removes redundant sortingLayerID (keeps sortingLayer)
Converts 0/1 to true/false for boolean fields
Converts bitmasks to layer arrays or 'all'
Simplifies Unity events to show method names
Inputs: filePath (required), config.
parse_unity_prefabA
Deprecated alias for parse_unity_file. Use parse_unity_file for new clients.
WORKFLOW: For best results with asset name resolution, call init_unity_project first. If already initialized, the cache is loaded automatically.
Inputs: filePath (required), config.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Most tools are distinct and clearly scoped, but parse_unity_file and parse_unity_prefab are duplicates, even though the latter is explicitly marked as deprecated. This could cause an agent to accidentally select the wrong one.
All tool names follow a consistent verb_noun snake_case pattern (init_, browse_, parse_, list_). Even the deprecated alias parse_unity_prefab follows the same pattern, maintaining predictability.
Five tools is a well-scoped set for a parser MCP. Each tool serves a clear step in the workflow: initialize, browse, list, and parse. No unnecessary bloat or missing core functionality.
The tool surface covers the full read-only workflow: project initialization for caching, navigation, asset discovery, and detailed parsing. The deprecated alias is redundant but doesn't create a functional gap. No obvious missing operations for the stated domain.
Maintenance
Related MCP Connectors
Polished system design diagrams (SVG/PNG) from a tiny YAML spec, ~18x fewer tokens than raw SVG.
Same functionality, consuming only 1/20 of the context window tokens.
Any URL to clean markdown/JSON; PDF, XLSX, CSV, DOCX to text and tables. Free tier for agents.
Read PDFs and images as markdown or text, with exact costs and hard spend caps. $0.75/1k pages.
Related MCP Servers
- FlicenseCqualityBmaintenanceProvides AI assistants with structured access to Unity project metadata, build settings, and agent documentation directly from the filesystem. It enables querying project details and scene configurations without requiring the Unity Editor to be running.156246 npm7-
- AlicenseNot gradedqualityNot gradedmaintenanceExposes Unity Editor project context and manipulation tools to AI coding agents, enabling automated scene hierarchy analysis, script inspection, and asset management. It supports both read and write operations including GameObject editing, component configuration, and animation authoring within the Unity environment.2-
- FlicenseNot gradedqualityDmaintenanceParses USD/USDZ/USDA files into structured JSON for AI agents, enabling scene graph hierarchy, material shader graphs, spatial positions, and entity relationship analysis via CLI and MCP tools.1-
- AlicenseNot gradedqualityCmaintenanceMCP server for safely inspecting and editing Unity/VRChat prefabs, scenes, and assets. It diagnoses override collisions, broken references, and runtime exceptions, with read-only YAML analysis and write operations via an Editor Bridge.12MIT