unity-asset-reference-mcp

Index a Unity project's assets into a reusable SQLite reference graph, then query it three ways: a CLI, an MCP server (for Claude and other agents), and a local web viewer. Unity-only.

• Impact analysis — "what references this material?" before you change it

• Unused-asset detection — orphans nothing loads (Addressables-aware)

• Dependency tracing — the full closure a scene/prefab pulls in

• Broken-reference detection — refs to deleted/missing assets

• Reusable artifact — a plain .sqlite any tool can open; no lock-in

It reads Unity's own serialization (.meta GUIDs + YAML {fileID, guid} refs), so the graph is exact — no heuristics, no AST. Requires Asset Serialization: Force Text (Unity's default for version control).

Requirements

• Node.js ≥ 20

• A Unity project using Force Text serialization

• better-sqlite3 builds via prebuilt binaries during install (native module)

Related MCP server: prefab-sentinel

Install

npm install -g unity-asset-reference-mcp

This puts three commands on your PATH:

Without a global install (npx): the MCP server's bin name matches the package, so npx -y unity-asset-reference-mcp … works directly. For the other two bins, name the package with -p:

npx -y unity-asset-reference-mcp --project /path/to/UnityProject          # MCP server
npx -y -p unity-asset-reference-mcp unity-asset-reference-mcp-index index /path   # indexer
npx -y -p unity-asset-reference-mcp unity-asset-reference-mcp-web --db <index.db> # viewer

1. Index a project

Builds <project>/.asset-memory/index.db.

unity-asset-reference-mcp-index index /path/to/UnityProject --force

Add this to your Unity project's .gitignore — ignore the live index, but commit the config and (optional) shared snapshot:

# unity-asset-reference-mcp: ignore the live index, keep config + shared snapshot
.asset-memory/index.db
.asset-memory/index.db-*
.asset-memory/*.building-*
.asset-memory/verify.json
.asset-memory/verify-report.json

2. Verify parser accuracy (optional)

Verification is a manual accuracy check. Install the Unity Editor exporter separately through Unity Package Manager, keeping the Node tool and Unity integration independently installable:

https://github.com/JVinceW/uasset-reference-memory-mcp.git?path=/unity/com.jvincew.assetreferencememory#<release-tag>

In Unity, run Tools > Asset Reference Memory > Export Verification. It writes <project>/.asset-memory/verify.json. Compare that export with the index through the CLI:

unity-asset-reference-mcp-index verify-index /path/to/UnityProject \
  --verify /path/to/UnityProject/.asset-memory/verify.json

The command exits successfully when differences are found. It prints a bounded summary and writes every missed/extra edge to <project>/.asset-memory/verify-report.json. MCP clients use verify_index(verifyJsonPath) and receive the same summary plus the report path.

3. MCP server (works with any MCP client)

This is a standard stdio MCP server — it works with any MCP-compatible host: Claude Code/Desktop, Cursor, Windsurf, Cline, VS Code (Copilot agent), Zed, and others. Nothing is Claude-specific; only where you put the config differs.

Generic config (Claude Desktop, Cursor, Windsurf, Cline, and most hosts use this mcpServers shape):

{
  "mcpServers": {
    "unity-asset-graph": {
      "command": "npx",
      "args": ["-y", "unity-asset-reference-mcp", "--project", "/path/to/UnityProject"]
    }
  }
}

Where that config lives, per host:

Prerequisites: Node ≥ 20 on PATH (for npx), and a Unity project on Force Text serialization. You do not need to pre-index — call the index_project tool once from the agent and it builds <project>/.asset-memory/index.db; the read tools return a clear no-index error until you do.

Tools exposed: index_project, index_status, get_dependencies, find_references, find_unused_assets, trace_path, search_assets, get_addressable_info, search_addressables, list_addressable_groups, get_overview, get_edges, verify_index, export_graph_json, and manage_adr.

The Addressables tools provide read-only entry lookup, filtered discovery, and group inventory. indexedSourceBytes is source-file size, not built bundle size, and reachableOnlyBecauseAddressable is a review signal rather than deletion safety. See docs/product/addressables.md.

Indexing follows Unity's identity model: an asset and its sibling .meta are one logical row, the GUID is stable identity, and the path is mutable. A normal incremental refresh observes the newer asset/.meta modification time and treats a GUID at a new path as one update. A new GUID at an old path is reported as removal plus addition with a guid-replaced warning. Missing, orphaned, or invalid .meta state is warned and skipped until Unity or source control restores a complete pair; duplicate GUIDs stop the refresh without replacing the last good index.

Agent refresh policy: before the first graph-dependent operation when freshness is unknown, call index_project once in incremental mode. Reuse that index for subsequent read-only queries, then refresh once after each coherent batch of asset/.meta changes. Use force: true only when guaranteed freshness is required. index_status reports stored index metadata; it does not scan live assets or prove freshness, and query tools never trigger hidden indexing.

3. Web viewer

# server flavor — serves the viewer + a JSON API over the index
unity-asset-reference-mcp-web --db /path/to/UnityProject/.asset-memory/index.db
# open http://localhost:7777

There is also a static flavor: open dist/web/public/viewer.html in a browser and pick a .db — it runs the same queries entirely in-browser (WASM SQLite), no server. Both share one query layer.

Team sharing (snapshots)

Instead of every teammate re-indexing from scratch, commit a compressed snapshot and let them restore it — the same idea as codebase-memory's .codebase-memory/.

# after indexing, export a shareable snapshot (or pass --snapshot to `index`)
unity-asset-reference-mcp-index snapshot /path/to/UnityProject
# -> .asset-memory/index.db.br  (brotli, ~85% smaller) + artifact.json + .gitattributes

# a teammate who clones + pulls restores the live index with no re-index:
unity-asset-reference-mcp-index restore /path/to/UnityProject

The MCP server and web viewer auto-restore from a snapshot on first use if the live index is missing, so a fresh clone "just works". Commit these:

.asset-memory/config.json       # per-project settings (below)
.asset-memory/index.db.br       # compressed shared index
.asset-memory/artifact.json     # snapshot metadata (schema, commit, counts)
.asset-memory/.gitattributes    # marks the blob binary + merge=ours

artifact.json records the git commit and counts the snapshot was built at, so you can tell when it's stale and re-run index --snapshot.

Configuration

Optional per-project .asset-memory/config.json (see docs/product/configuration.md):

{
  "unused": { "addressableRoots": "auto" },
  "scan":   { "ignore": ["**/ThirdParty/**", "*.bak"], "ignoreDefaults": true }
}

• unused.addressableRoots (auto|on|off) — count Addressable entries as roots for unused detection (query-time; auto = on if the project uses Addressables). Overridable per call.

• scan.ignore / scan.ignoreDefaults — extra ignore globs (index-time).

The SQLite artifact

Open .asset-memory/index.db with any SQLite tool. Core tables: assets (nodes), edges (references), unresolved_refs (broken refs), addressable_groups, addressable_entries, addressable_entry_labels, and index_meta. Schema: docs/product/asset-graph-model.md.

Schema 3 normalizes Addressables into addressable_groups, addressable_entries, and addressable_entry_labels. JSON exports include each entry's read-only state, owning group identity, and sorted labels. Older generated indexes and snapshots must be rebuilt with index_project; they are not migrated in place.

Known limitations

• Code-based refs not tracked: Resources.Load("path") and hard-coded Addressable address strings in C# aren't scanned yet, so find_unused output is candidates — verify against your loading code.

• Asset-level granularity: edges are asset→asset (not per-GameObject/fileID).

• Read-only Addressables Stage 1: group schemas, profiles, providers, packing/compression, build/load paths, content-update settings, and bundle analysis are deferred.

• Incremental re-index uses filesystem modification times for speed and can miss timestamp-preserving edits. Use --force for a guaranteed-freshness rebuild from current readable project contents; it still reports unreadable or incomplete project state rather than modifying Unity assets.

Development

npm install
npm test        # vitest
npm run build   # tsc + copy web assets to dist/

This repo uses a Git-native, text-first development workflow (see docs/WORKFLOW.md); it is not part of the shipped package.

License

MIT — see LICENSE.