unity-mcp

The first Model Context Protocol server for Unity projects.
Give Claude, Cursor, Windsurf, and any MCP-compatible AI assistant real understanding of your Unity scenes, prefabs, and C# scripts — not just file search.

---

The Problem

When you ask an AI assistant about your Unity project, it reads .cs files — but Unity's real architecture lives in YAML. A PlayerController script might be attached to 12 different prefabs, referenced by 3 different managers, and spawned at runtime by 2 different spawners. None of that is visible from C# alone.

The Solution

unity-mcp exports your project's complete scene graph (GameObjects → Components → Inspector references → runtime spawns), turns it into a queryable knowledge graph, and makes it available to any MCP-compatible AI through a set of fast, structured tools.

AI asks: "Which scripts reference the Player prefab?"
unity-mcp answers with: 7 scripts, 12 scene objects, 3 runtime spawn sites
— in under 50ms

---

Demo

You: What components are on the EnemyBoss prefab?

Claude: EnemyBoss.prefab has 4 components:
  • EnemyAI       (Assets/Scripts/AI/EnemyAI.cs)
  • EnemyParent   (Assets/Scripts/Enemy/EnemyParent.cs)
  • PhotonView    (Photon PUN — no script file)
  • NavMeshAgent  (Unity built-in)

Inspector refs wired up:
  EnemyAI.player         → Player (scene object, tag: Player)
  EnemyAI.spawnPoint     → SpawnPoint (scene object)
  EnemyParent.healthBar  → HealthBar.prefab

Runtime: EnemySpawner.cs line 47 instantiates EnemyBoss via enemyPrefab field.

---

Quick Start (5 minutes)

1 — Export your Unity scene graph

Copy unity-editor/UnitySceneGraphExporter.cs into your Unity project's Assets/Editor/ folder.

Then in Unity:

Tools → Export Unity Graph

This creates Assets/unity_graph.json.

2 — Install and run the MCP server

npx unity-mcp --graph /path/to/your/project/Assets/unity_graph.json

Or install globally:

npm install -g unity-mcp
unity-mcp --graph ./Assets/unity_graph.json

3 — Connect to your AI assistant

Claude Code (~/.claude/settings.json):

{
  "mcpServers": {
    "unity": {
      "command": "unity-mcp",
      "args": ["--graph", "/absolute/path/to/Assets/unity_graph.json"]
    }
  }
}

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "unity": {
      "command": "npx",
      "args": ["-y", "unity-mcp", "--graph", "/absolute/path/to/Assets/unity_graph.json"]
    }
  }
}

See examples/ for Cursor, Windsurf, and other clients.

---

Available MCP Tools

Tool	Description
list_scenes	List all scenes in the project
list_prefabs	List all prefabs in the project
get_scene_objects	Get all GameObjects in a specific scene
get_prefab_components	Get all components attached to a prefab or GameObject
find_script_usages	Find every scene object and prefab using a C# script
get_inspector_refs	Get all Inspector-wired field references for a component
get_runtime_spawns	Get all Instantiate() call sites for a script
query_by_tag	Find all GameObjects with a specific Unity tag
query_by_layer	Find all GameObjects on a specific layer
get_hierarchy	Get the full parent→child hierarchy for a scene or prefab

---

Example Queries

Once connected, ask your AI assistant anything about your project structure:

"What prefabs does EnemySpawner.cs instantiate at runtime?"
"List every GameObject tagged 'Player' across all scenes."
"Show me the full hierarchy of the MainMenu scene."
"What scripts are attached to the Cart prefab?"
"Which scripts have Inspector references to the AudioManager?"
"Find all prefabs that use the RigidBody component."
"What are all the runtime spawn sites in the project?"

---

Architecture

Unity Editor
  └─ Tools → Export Unity Graph
        └─ Assets/unity_graph.json    (static export)
                     │
                     ▼
         unity-mcp (Node.js MCP server)
           Load → Index in memory → Serve MCP tools
                     │
         ┌───────────┼───────────────┐
         ▼           ▼               ▼
      Claude       Cursor        Windsurf
   (Claude Code) (Composer AI)  (Cascade AI)

The graph has three layers:

Layer	What it captures
Code Graph	C# classes, methods, calls (handled by your IDE)
Static Scene Graph	Scene → GameObject → Component → Inspector refs (unity-mcp)
Runtime Spawn Graph	Instantiate() call sites with field names and line numbers (unity-mcp)

---

Why Not Just Use File Search?

Capability	File Search	unity-mcp
Find what script is on a prefab	❌ YAML is opaque	✅ Instant
Trace inspector references	❌ Requires GUID resolution	✅ Pre-resolved
Find runtime spawned objects	❌ Requires AST + heuristics	✅ Indexed
Query by tag or layer	❌ Not possible	✅ Sub-10ms
Understand scene hierarchy	❌ YAML noise	✅ Clean tree

---

Re-exporting After Changes

Run Tools → Export Unity Graph any time you change scenes or prefabs. The export takes ~5 seconds for a typical project (our test project: 1,244 prefabs, 8 scenes, 70K+ nodes).

---

Supported Unity Versions

• Unity 2021.x LTS ✅
• Unity 2022.x LTS ✅
• Unity 6 ✅

---

Contributing

Contributions welcome! See CONTRIBUTING.md.

Planned features:

• [ ] Incremental export (only changed scenes/prefabs)
• [ ] Godot scene format support
• [ ] Watch mode (auto-re-export on save)
• [ ] VS Code extension
• [ ] Web UI for graph visualization

---

License

MIT © 2026 — See LICENSE

---

Built with real game project experience. Tested on a 291-file, 1,244-prefab Unity 2022 production project.