EYamanS/mcp-unity-server

MCP Unity Server

AI-powered Unity Editor integration via Model Context Protocol. Generate games, manipulate scenes, and automate Unity workflows directly from Cursor/Claude!

🎮 What is This?

An MCP (Model Context Protocol) server that connects AI assistants like Claude/Cursor to Unity Editor, enabling:

• 🤖 AI-powered game generation - "Create a platformer level with enemies"
• 🎨 Scene manipulation - Create, modify, delete GameObjects via natural language
• ⚙️ Component configuration - Setup physics, materials, lighting with AI
• 📦 Asset management - Generate prefabs, materials, scripts automatically
• 🖼️ UI generation - Create complete UI systems instantly
• 📝 Script generation - Auto-generate MonoBehaviour/NetworkBehaviour scripts

🚀 Quick Start

1. Install MCP Server

Option A: Use with npx (No installation needed)

{
  "mcpServers": {
    "unity": {
      "command": "npx",
      "args": ["-y", "mcp-unity-server-yamansivrikaya"]
    }
  }
}

Option B: From GitHub

{
  "mcpServers": {
    "unity": {
      "command": "npx",
      "args": ["-y", "github:EYamanS/mcp-unity-server"]
    }
  }
}

Add the above to your .cursor/mcp.json file.

2. Install Unity Bridge

Prerequisites:

• Unity 2020.3+
• Newtonsoft.Json package (see installation guide)

Installation:

# Clone or download this repo
git clone https://github.com/EYamanS/mcp-unity-server.git

# Copy Unity bridge to your project
cp -r mcp-unity-server/UnityMCP/* /path/to/YourUnityProject/Assets/Editor/UnityMCP/

Install Newtonsoft.Json in Unity:

1. Open Package Manager: Window > Package Manager
2. Click + → Add package by name
3. Enter: com.unity.nuget.newtonsoft-json
4. Click Add

3. Start Using

1. Restart Cursor to load MCP server
2. Open Unity Editor with your project
3. Verify connection: Window > Unity MCP > Control Panel (should show green ●)
4. Start creating! Ask AI to generate game objects

✨ Example Usage

Ask your AI assistant:

"Create a simple platformer level in Unity with a player sphere that has physics, a ground plane, some cube obstacles positioned randomly, a camera at (0, 5, -10) looking at the player, and directional lighting"

The AI will automatically:

1. Create primitives for ground and obstacles
2. Setup player with Rigidbody and collider
3. Add and position camera
4. Create directional light
5. Position everything correctly
6. Save the scene

🎯 Features

30+ Game Generation Tools

📚 Available Tools

🏗️ Architecture

Clean, modular design following SOLID principles:

┌─────────────┐
│   Cursor    │  (AI Assistant)
└──────┬──────┘
       │ stdio (MCP Protocol)
       ▼
┌─────────────────┐
│  Node.js MCP    │  (This Server)
│     Server      │
└──────┬──────────┘
       │ WebSocket (port 8765)
       ▼
┌─────────────────┐
│  Unity C# Bridge│  (18 Tool Classes)
└──────┬──────────┘
       │ Unity Editor API
       ▼
┌─────────────────┐
│  Unity Editor   │  (Your Game)
└─────────────────┘

Unity Bridge Structure:

• Partial Classes: Organized by responsibility
• 18 Specialized Tools: Each category in its own file
• Router Pattern: Central dispatch to appropriate handler
• Shared Utilities: Common operations abstracted

📦 Installation

Prerequisites

• Node.js 18+ (Download)
• Unity 2020.3+ (tested on Unity 6)
• Cursor with MCP support
• Newtonsoft.Json in Unity (usually pre-installed)

Setup

1. Configure Cursor - Add to .cursor/mcp.json:

{
  "mcpServers": {
    "unity": {
      "command": "npx",
      "args": ["-y", "github:EYamanS/mcp-unity-server"]
    }
  }
}

2. Install Unity Bridge:

git clone https://github.com/EYamanS/mcp-unity-server.git
cp -r mcp-unity-server/UnityMCP/* /path/to/YourUnityProject/Assets/Editor/UnityMCP/

3. Restart Cursor

4. Verify: In Unity, check Window > Unity MCP > Control Panel shows ● Connected

🎨 Example Projects

Create a platformer level with:
- Player sphere at (0, 2, 0) with rigidbody and sphere collider
- Ground plane at origin scaled to 20x1x20
- 5 cube obstacles positioned randomly
- Camera at (0, 5, -10) looking at origin
- Directional light from above
- Red material on player
- Blue material on ground

Create a main menu UI with:
- Canvas in screen space overlay mode
- Background panel covering full screen
- Title text at top saying "My Game"
- Three buttons stacked vertically: Play, Settings, Quit
- Each button 200x50 pixels

Create a physics sandbox:
- Large cube as ground with box collider
- 10 spheres dropped from random heights with rigidbodies
- Each sphere with random colored material
- Camera positioned to see the action

🛠️ Development

# Clone repository
git clone https://github.com/EYamanS/mcp-unity-server.git
cd mcp-unity-server

# Install dependencies
npm install

# Build
npm run build

# Test locally
npm run dev

📖 Documentation

• - Complete API documentation
• - Design & patterns
• - Detailed Unity setup

🤝 Contributing

Contributions welcome! To add new tools:

1. Node.js side: Add tool definition in src/index.ts
2. Unity side: Create tool class in UnityMCP/Tools/YourTool.cs
3. Router: Add routing in UnityMCP/UnityMCPBridge.Router.cs
4. Document: Update UnityMCP/TOOLS_REFERENCE.md

🐛 Troubleshooting

MCP server not connecting:

• Check Cursor MCP logs in output panel
• Verify Node.js 18+ is installed
• Restart Cursor completely

Unity not connecting:

• Check Unity Console for WebSocket errors
• Verify bridge files are in Assets/Editor/UnityMCP/
• Port 8765 must be free
• Check Window > Unity MCP > Control Panel

Tools not working:

• Ensure both Node and Unity bridges are up to date
• Rebuild Unity bridge if you made changes
• Check Unity Console for detailed error messages

📋 Requirements

• Node.js: 18.0.0 or higher
• Unity: 2020.3+ (tested on Unity 6)
• Cursor: Latest version with MCP support
• Newtonsoft.Json: For Unity (usually included)

📝 License

MIT License - see file

🙏 Credits

Built with:

• Model Context Protocol by Anthropic
• Unity Editor
• Cursor

🌟 Star History

If this helps you build games faster, give it a star! ⭐

Made with ❤️ for Unity developers who want AI superpowers

🔗 Links

• GitHub Repository
• Report Issues
• MCP Documentation