mitchchristow/unity-mcp

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
• 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+ (6000.x)
• Node.js 18+
• Cursor IDE (recommended) 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 for detailed instructions.

VS Code (✅ Supported via Kilo and Copilot)

VS Code supports MCP servers through the Kilo and GitHub Copilot extension (and others).

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

Manual Setup: 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"
       }
     }
   }
   

See 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 folder in Unity Hub (requires Unity 6+)

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
   │       │   ├── 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
   

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

# Test RPC endpoint
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}'

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

Key Files to Know

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 for the roadmap of planned improvements.

✨ Features

📦 Available Tools, Resources & Prompts

Tools (80)

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

Resources (42)

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

Prompts (8)

Pre-defined workflow templates for complex tasks:

🏗 Architecture

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

Components

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:

See also: 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 for the roadmap of planned features.

📄 License

MIT License - see for details.

Made with ❤️ for the Unity + AI community