zabaglione/mcp-server-unity

Unity 6 MCP Bridge v3.0.0

Direct Unity API integration for AI-powered game development

|

Unity 6 MCP Bridge provides seamless integration between AI assistants (like Claude) and Unity Editor through direct Unity API calls. This is a complete rewrite for Unity 6000+, featuring industry-standard diff processing and robust error handling.

🚀 Features

Unity 6 Integration

• Direct Unity API calls via Named Pipes/Domain Sockets
• Real-time synchronization with Unity Editor
• Native AssetDatabase operations (no more meta file issues!)
• Roslyn-powered code analysis and IntelliSense
• Unity 6 template system for code generation

Script Operations

• script_create - Generate scripts from Unity 6 templates (MonoBehaviour, ScriptableObject, Editor, Custom)
• script_read - Read script content with streaming support for large files
• script_delete - Safe deletion with reference checking
• script_rename - Rename with automatic class name updates
• script_update_diff - Apply diffs with fuzzy matching and whitespace handling
• script_apply_patch - Batch apply multiple file changes with rollback support
• script_create_diff - Generate unified diffs between contents
• script_validate_diff - Pre-validate diffs before applying

Folder Management

• folder_create - Create with automatic parent directories
• folder_delete - Safe deletion with asset cleanup
• folder_rename - Rename with reference updates
• folder_list - List contents with Unity metadata (GUIDs, types)

Advanced Diff Processing (v3.0)

• Industry-standard diff-match-patch algorithm by Google
• Fuzzy matching for handling minor differences
• BOM preservation for Unity files
• Detailed error reporting with line-by-line analysis
• Performance optimized - processes 10,000 lines in <5ms

Installation

Prerequisites

• Unity 6000.0 or later (Required)
• Node.js 18+
• Claude Desktop or compatible MCP client

Quick Install with Desktop Extension (NEW! 🎉)

The easiest way to install Unity MCP Bridge is using the Desktop Extension:

1. Download: Get unity-mcp-bridge.dxt from Releases
2. Install: In Claude Desktop, go to Extensions → Install from file → Select the .dxt file
3. Configure: Set your Unity project path in the extension settings
4. Done! Unity Bridge will auto-install in your project when you first use it

Manual Installation

1. Install MCP Bridge

npm install -g unity-mcp-bridge

2. Install Unity Bridge in Your Project

Use the built-in installer:

# After configuring Claude Desktop, use this MCP tool:
bridge_install --projectPath /path/to/your/unity/project

Or manually:

1. Copy the Unity scripts from src/unity-scripts/
2. Place in Assets/Editor/MCP/ in your Unity project
3. Unity will automatically compile and start the bridge

3. Configure Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "unity-bridge": {
      "command": "unity-mcp-bridge",
      "args": []
    }
  }
}

📖 Usage Examples

Setting Project Path

# Set the Unity project to work with
project_set_path /path/to/your/unity/project

# Check connection status
project_get_info

Script Operations

# Create a new player controller
script_create Player --template MonoBehaviour --folder Assets/Scripts/Player

# Create with custom content
script_create GameManager --content "using UnityEngine;\n\npublic class GameManager : MonoBehaviour\n{\n    // Game logic here\n}"

# Read existing script
script_read Assets/Scripts/Enemy.cs

# Rename with class update
script_rename Assets/Scripts/Enemy.cs EnemyAI

Advanced Diff Operations

# Apply a diff to update code
script_update_diff Assets/Scripts/Player.cs "--- a/Player.cs\n+++ b/Player.cs\n@@ -10,7 +10,7 @@\n-    private float speed = 5.0f;\n+    private float speed = 10.0f;"

# Use fuzzy matching for inexact matches
script_update_diff Assets/Scripts/Enemy.cs "$DIFF_CONTENT" --fuzzy 80 --ignoreWhitespace

# Validate before applying
script_validate_diff Assets/Scripts/Player.cs "$DIFF_CONTENT"

Folder Operations

# Create nested folders
folder_create Assets/Scripts/AI/Behaviors --recursive

# List folder contents with metadata
folder_list Assets/Scripts

# Rename folder
folder_rename Assets/Scripts/AI Assets/Scripts/ArtificialIntelligence

🔧 Technical Details

Architecture

• Unity Bridge Client: WebSocket/TCP communication with Unity Editor
• API Layer: Modular API design (Script, Folder, Diff APIs)
• MCP Server: Standard I/O interface for Claude Desktop
• Error Handling: Comprehensive error types with actionable messages

Performance

• Large file support (streaming for >1MB files)
• Batch operations support
• Connection pooling and retry logic
• Optimized diff processing (<5ms for 10k lines)

Testing

• Unit test coverage: 100%
• Integration tests with Unity Bridge mock
• Performance benchmarks included
• Japanese/UTF-8 fully supported

📋 API Reference

See for comprehensive testing results and API examples.

⚠️ Breaking Changes from v2.x

• Complete API redesign for Unity 6
• Requires Unity 6000.0 or later
• New Unity Bridge architecture
• Industry-standard diff processing
• All v2.x service-based APIs removed

🛠️ Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Start in development mode
npm run dev

Building Desktop Extension

To create a Desktop Extension package (.dxt):

# Build the extension package
npm run extension:build

# This creates unity-mcp-bridge.dxt ready for distribution

The extension includes:

• Pre-built server files
• All dependencies bundled
• Icon and metadata
• Auto-configuration support

🤝 Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Run tests: npm test
4. Submit a pull request

📜 License

MIT License - see for details.

🙏 Acknowledgments

• Google's diff-match-patch library
• Model Context Protocol by Anthropic
• Unity Technologies for Unity 6

Note: This is a complete rewrite (v3.0) with breaking changes. For v2.x documentation, see the v2.x branch.