Unity MCP Server

Control the Unity Editor directly from your AI Assistant.

This project implements a Model Context Protocol (MCP) server that runs inside the Unity Editor. It allows AI-powered IDEs like Cursor to manipulate scenes, write scripts, and control play mode through natural language, enabling direct GenAI usage in game development.

---

📖 Table of Contents

• For Users: Quick Start
• For Developers: Contributing
  • Supported Unity Versions & Worktrees
• Features
• Available Tools, Resources & Prompts
• Architecture
• Documentation
• License

---

🚀 For Users: Quick Start

Want to use this MCP server to build Unity games with AI? Follow these steps:

Prerequisites

• Unity 6.2, 6.3 LTS, or 6.5 (see supported versions below)
• Node.js 18+
• Antigravity, Cursor IDE, VS Code with Claude Code, or another MCP-compatible IDE

Step 1: Install the Unity Package

Option A: From GitHub (Recommended)

1. Open your Unity project
2. Go to Window > Package Manager
3. Click + → Add package from git URL...
4. Enter:

   https://github.com/mitchchristow/unity-mcp.git?path=/Packages/org.christowm.unity.mcp
   

Option B: Clone for Local Development

git clone https://github.com/mitchchristow/unity-mcp.git
cd unity-mcp

Then open the folder in Unity Hub.

Step 2: Install Gateway Dependencies

cd gateway
npm install

Step 3: Connect Your IDE

Cursor (✅ Fully Supported)

Cursor is the recommended IDE with full MCP support.

1. Open Unity and wait for [MCP] HTTP Server started in the Console
2. Open the project folder in Cursor
3. The MCP server starts automatically via .cursor/mcp.json
4. Start chatting! Try: "Create a red cube at position (0, 1, 0)"

Manual Setup (if auto-detection fails):

Create .cursor/mcp.json:

{
  "mcpServers": {
    "unity": {
      "command": "node",
      "args": ["./gateway/index.js"],
      "cwd": "${workspaceFolder}"
    }
  }
}

Antigravity (⚠️ Global Config Only)

Note: According to the Antigravity MCP documentation, Antigravity only supports global MCP configuration. Per-project configuration is not available.

Setup:

1. Open Antigravity → Click "..." → "Manage MCP Servers" → "View raw config"
2. Add this configuration (update the path to your installation):

{
  "mcpServers": {
    "unity": {
      "command": "node",
      "args": ["/absolute/path/to/unity-mcp/gateway/index.js"],
      "cwd": "/absolute/path/to/unity-mcp"
    }
  }
}

See Antigravity Integration Guide for detailed instructions.

VS Code (✅ Supported via Kilo, Copilot, and Claude Code)

VS Code supports MCP servers through the Kilo, GitHub Copilot, and Claude Code extensions (and others).

Automatic Setup: This repository includes a .vscode/mcp.json file. If you open this folder in VS Code with the GitHub Copilot or Kilo extension installed, the Unity MCP server should be automatically detected.

Manual Setup (Kilo / GitHub Copilot): If you are adding the Unity MCP server to a different workspace:

1. Create a .vscode/mcp.json file in your project root.
2. Add the configuration:

   {
     "servers": {
       "unity": {
         "command": "node",
         "args": ["/path/to/unity-mcp/gateway/index.js"],
         "type": "stdio"
       }
     }
   }
   

Claude Code Setup: This repository includes a .mcp.json file for Claude Code support. If you have the Claude Code extension installed in VS Code, the Unity MCP server will be automatically detected when you open this project.

For manual setup in a different workspace, create a .mcp.json file in your project root:

{
  "mcpServers": {
    "unity": {
      "command": "node",
      "args": ["./gateway/index.js"],
      "cwd": "${workspaceFolder}"
    }
  }
}

See VS Code Integration Guide for more details.

Step 4: Start Building!

Once connected, you can use natural language to control Unity:

• "Create a 2D player character with WASD movement"
• "Add a Rigidbody2D to the selected object"
• "Set up a turn-based battle system"
• "What objects are in my scene?"

---

🛠 For Developers: Contributing

Want to extend the MCP server, fix bugs, or add new features? This section is for you.

Development Setup

1. Clone the repository:

   git clone https://github.com/mitchchristow/unity-mcp.git
   cd unity-mcp
   

2. Open in Unity: Open the repo root (or a version worktree) in Unity Hub.

3. Install gateway dependencies:

   cd gateway
   npm install
   

4. Project Structure:

   unity-mcp/
   ├── Packages/org.christowm.unity.mcp/   # Unity Editor package
   │   └── Editor/
   │       ├── MCP/                        # MCP server implementation
   │       │   ├── Rpc/Controllers/        # RPC method handlers
   │       │   ├── McpObjectReference.cs   # Unity 6.2–6.5 object ID bridge
   │       │   ├── Events/                 # WebSocket event system
   │       │   └── Progress/               # Progress tracking
   │       ├── Networking/                 # HTTP & WebSocket servers
   │       └── IPC/                        # Named Pipe server
   ├── gateway/                            # Node.js MCP gateway
   │   └── index.js                        # Tool/Resource/Prompt definitions
   ├── Docs/                               # Documentation (Docusaurus)
   ├── .cursor/                            # Cursor IDE MCP config
   ├── ide-integrations/                   # IDE config templates
   │   ├── antigravity/                    # Global config template
   │   └── vscode/                         # VS Code extension (WIP)
   └── TODO.md                             # Future improvements roadmap
   

Supported Unity Versions & Worktrees

This project is tested on three Unity 6 editor lines. Use a separate project folder for each version so ProjectSettings/ and Library/ are not overwritten when switching editors.

Unity	Hub version (example)	Local worktree folder	Git branch
6.2	6000.2.x	worktrees/unity-620	worktree/unity-620
6.3 LTS	6000.3.x	worktrees/unity-630-lts	worktree/unity-630-lts
6.5	6000.5.x	worktrees/unity-6500	worktree/unity-6500

The repo root (unity-mcp/) stays on main for git work and general development. Version worktrees are local-only (/worktrees/ is in .gitignore).

Create worktrees (from repo root, after clone):

git worktree add -B worktree/unity-620      worktrees/unity-620      main
git worktree add -B worktree/unity-630-lts  worktrees/unity-630-lts  main
git worktree add -B worktree/unity-6500     worktrees/unity-6500     main

Open each folder in Unity Hub with the matching editor. Expect Unity to upgrade that copy's ProjectVersion.txt on first launch — that is normal and stays local to that worktree.

Object IDs: Unity 6.5 returns large ulong Entity IDs on the wire; 6.2/6.3 use int Instance IDs. Package code routes both through McpObjectReference (#if UNITY_6000_5_OR_NEWER).

Adding New Features

Adding a New Tool

1. Create/update a Controller in Packages/.../Rpc/Controllers/:

   public static class MyController
   {
       public static void Register()
       {
           JsonRpcDispatcher.RegisterMethod("unity.my_method", MyMethod);
       }
   
       private static JObject MyMethod(JObject p)
       {
           // Implementation
           return new JObject { ["ok"] = true };
       }
   }
   

2. Register in McpServer.cs:

   MyController.Register();
   

3. Add tool definition in gateway/index.js:

   {
     name: "unity_my_tool",
     description: "What this tool does",
     inputSchema: {
       type: "object",
       properties: { /* ... */ },
       required: ["param1"],
     },
   },
   

4. Add handler in the CallToolRequestSchema handler if needed.

Adding a New Resource

1. Add RPC method in Unity (similar to tools)
2. Add resource definition to RESOURCES array in gateway/index.js
3. Add URI-to-method mapping in ReadResourceRequestSchema handler

Adding a New Prompt

Add to the PROMPTS array and implement in generatePromptContent() function in gateway/index.js.

Testing

Quick RPC check (Unity open, MCP server running):

curl -X POST http://localhost:17890/mcp/rpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"unity.get_project_info","params":{},"id":1}'

Smoke test (validates primitive → transform → material on any supported Unity version):

1. unity.create_primitive — Sphere, name e.g. SmokeSphere
2. unity.set_transform — position (0,0,0), scale (5,5,5)
3. unity.create_material — e.g. SmokeMaterial (Standard shader)
4. unity.set_material_property — set _Color (e.g. red or yellow)
5. unity.set_material — apply material to the sphere
6. unity.get_object_details — confirm transform and material

Batch dry-run: Call the unity_batch tool with "dryRun": true to validate tool names and $N interpolation without modifying the scene.

Operation audit log: Read the unity://operations/history resource to review recent MCP tool calls recorded by the gateway (tool name, args, success/error, duration).

EditMode tests: Window → General → Test Runner → EditMode (4 tests in the package).

# WebSocket events
wscat -c ws://localhost:17891/mcp/events

Key Files to Know

File	Purpose
gateway/index.js	MCP gateway - all tools, resources, prompts
McpServer.cs	Unity-side server initialization
HttpServer.cs	HTTP JSON-RPC handler
WebSocketServer.cs	Real-time event streaming
JsonRpcDispatcher.cs	Routes RPC calls to controllers

Pull Request Guidelines

1. Create a feature branch: feature/my-feature
2. Follow existing code style
3. Update documentation if adding user-facing features
4. Test with Cursor to verify MCP integration
5. Update TODO.md if implementing a backlog item

See TODO.md for the roadmap of planned improvements.

---

✨ Features

Category	Capabilities
Scene Control	Create, move, delete, inspect GameObjects
Components	Add/remove components, modify properties via reflection
Assets	List and inspect materials, prefabs, scripts, textures
Scripting	Create scripts from templates, monitor compilation
Play Mode	Start, stop, pause the game
Lighting	Create lights, configure ambient lighting
Cameras	Create cameras, control Scene view
Physics	Gravity, raycasting, collision layers (2D & 3D)
UI	Create canvases, buttons, text, images
Terrain	Create and sculpt terrains
Particles	Create and configure particle systems
Navigation	NavMesh baking, agents, pathfinding
Audio	Audio sources, playback control
Build	Configure and execute builds
2D Development	Sprites, tilemaps, 2D physics
Batch Operations	Execute multiple tools in one call with result chaining, single undo, and optional dry-run validation
Operation Audit Log	Gateway records recent MCP tool calls; inspect via unity://operations/history
Prompts	8 workflow templates for common tasks
Events	Real-time scene/selection/console streaming

---

📦 Available Tools, Resources & Prompts

Tools (80)

The server exposes 80 tools organized by category. Many use an action parameter to consolidate related operations.

Tool	Description
unity_list_objects	List all GameObjects in the scene
unity_create_object	Create a new empty GameObject
unity_create_primitive	Create a primitive (Cube, Sphere, etc.)
unity_delete_object	Delete a GameObject
unity_set_transform	Set position, rotation, and scale
unity_selection	Selection: set, clear, select_by_name, focus
unity_find_objects	Find by: name, tag, component, or layer

Tool	Actions
unity_playmode	play, stop, pause
unity_undo_action	undo, redo, get_history, clear, begin_group, end_group
unity_component	add, remove, list, get_properties
unity_file	read, write, exists, list_dir, create_dir
unity_capture	game, scene
unity_animator	get_info, get_parameters, set_parameter, play_state
unity_build	set_target, add_scene, remove_scene, get_scenes, build
unity_package	get_info, add, remove, search
unity_window	open, close, focus, get_info
unity_sprite	create, set_sprite, set_property, get_info
unity_tilemap	create, set_tile, get_tile, fill, clear_all, get_info
unity_batch	Run multiple tools sequentially in one undo group; supports $0 result chaining and dryRun: true validation

Run several tool calls in one MCP request. The entire batch is wrapped in a single Unity undo group (one Ctrl+Z reverts all).

Result chaining: Use $0, $1, etc. in later args to reference prior results (e.g. "id": "$0.id").

Dry-run validation: Set "dryRun": true to validate tool names, interpolation, and RPC mapping without calling Unity or opening an undo group. Useful for checking a complex workflow before executing it.

{
  "dryRun": true,
  "operations": [
    { "tool": "unity_create_primitive", "args": { "type": "Cube", "name": "TestCube" } },
    { "tool": "unity_set_transform", "args": { "id": "$0.id", "position": { "x": 0, "y": 1, "z": 0 } } }
  ]
}

• Lighting: create_light, set_light_property, get_lighting_settings, set_ambient_light
• Cameras: create_camera, set_camera_property, get_camera_info, scene_view controls
• Physics: set_gravity, set_physics_property, raycast, layer_collision
• UI: create_canvas, create_ui_element, set_ui_text, set_ui_image, set_rect_transform
• Terrain: create_terrain, set_terrain_size, terrain_height, flatten_terrain
• Particles: create_particle_system, set_particle_module, particle_playback
• Navigation: navmesh_build, add_navmesh_agent, set_navmesh_destination, calculate_path
• Audio: create_audio_source, set_audio_source_property, audio_playback
• 2D Physics: physics_2d_body, physics_2d_query, set_physics_2d_property
• Scripting: create_script, get_component_api

Resources (43)

Resources provide read-only context that the AI reads automatically.

Category	Resources
Project	unity://project/info, unity://assets, unity://packages
Scene	unity://scene/hierarchy, unity://scene/list, unity://scene/stats, unity://scene/analysis
Selection	unity://selection, unity://console/logs
Objects	unity://lights, unity://cameras, unity://terrains, unity://particles, unity://ui/elements
Systems	unity://physics, unity://tags, unity://layers, unity://audio/settings
Navigation	unity://navmesh/settings, unity://navmesh/agents
Build	unity://build/settings, unity://build/targets
Events	unity://events/recent, unity://events/types, unity://events/status
2D	unity://sprites, unity://tilemaps, unity://tiles, unity://2d/physics
Scripting	unity://scripts/errors, unity://scripts/warnings, unity://scripts/templates, unity://components/types
Progress	unity://progress
Gateway	unity://operations/history — recent MCP tool calls (tool, args, RPC method, success/error, duration)

Prompts (8)

Pre-defined workflow templates for complex tasks:

Prompt	Description
create_2d_character	2D character with sprite, physics, movement script
setup_turn_based_system	Turn manager, units, action system
create_grid_map	Grid-based map with tilemap and pathfinding
create_ui_menu	UI menu (main, pause, settings, inventory, battle)
setup_unit_stats	ScriptableObject stats system for RPG/strategy
create_audio_manager	Audio singleton with BGM/SFX pooling
optimize_scene	Scene analysis and optimization recommendations
setup_save_system	JSON-based save/load system

---

🏗 Architecture

┌─────────────┐     stdio      ┌─────────────┐     HTTP      ┌─────────────┐
│   IDE/AI    │ ◄────────────► │   Gateway   │ ◄───────────► │    Unity    │
│  (Cursor)   │     MCP        │  (Node.js)  │   JSON-RPC    │   Editor    │
└─────────────┘                └─────────────┘               └─────────────┘
                                     │
                                     │ WebSocket
                                     ▼
                               Real-time Events

Components

Component	Port	Purpose
HTTP Server	17890	JSON-RPC command handling
WebSocket Server	17891	Real-time event streaming
Named Pipe	\\.\pipe\unity-mcp	Secure local IPC (Windows)
Node.js Gateway	stdio	MCP protocol translation

Performance

• Request queue with continuous processing via EditorApplication.update
• Automatic editor wake-up when Unity is in background
• Typical response times: 30-175ms

---

📚 Documentation

Full documentation is available in the Docs/ directory:

• RPC API Reference
• 2D Development Guide
• Scripting Assistance
• Event System
• IDE Configuration

See also: TODO.md for planned improvements.

---

🐛 Issues & Feature Requests

• Bug reports: Open an issue with steps to reproduce
• Feature requests: Open an issue and tag it with enhancement
• Questions: Use GitHub Discussions or open an issue

See TODO.md for the roadmap of planned features.

---

📄 License

MIT License - see LICENSE for details.

---

Made with ❤️ for the Unity + AI community