# 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.

[![npm version](https://img.shields.io/npm/v/unity-mcp.svg)](https://www.npmjs.com/package/unity-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-4B32C3)](https://modelcontextprotocol.io)
[![Unity 2021+](https://img.shields.io/badge/Unity-2021%2B-222222?logo=Unity)](https://unity.com)

---

## 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

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

Or install globally:
```bash
npm install -g unity-mcp
unity-mcp --graph ./Assets/unity_graph.json
```

### 3 — Connect to your AI assistant

**Claude Code** (`~/.claude/settings.json`):
```json
{
  "mcpServers": {
    "unity": {
      "command": "unity-mcp",
      "args": ["--graph", "/absolute/path/to/Assets/unity_graph.json"]
    }
  }
}
```

**Claude Desktop** (`claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "unity": {
      "command": "npx",
      "args": ["-y", "unity-mcp", "--graph", "/absolute/path/to/Assets/unity_graph.json"]
    }
  }
}
```

See [examples/](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](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](LICENSE)

---

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