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

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:

Why Not Just Use File Search?

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.