mcp-server-unity

zabaglione/mcp-server-unity

3.4

If you are the rightful owner of mcp-server-unity and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

Unity 6 MCP Bridge v3.0.0 provides seamless integration between AI assistants and Unity Editor through direct Unity API calls.

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


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