MCP for Unity: AI assistant bridge for Unity Editor

MCP for Unity is a bridge that connects AI assistants to the Unity Editor through the Model Context Protocol (MCP). It enables AI-driven game development workflows by giving LLMs the ability to directly control and manipulate your Unity projects.

Built and maintained by Coplay and sponsored by Aura, this open-source project (MIT license) allows AI clients like Claude Code, Cursor, VSCode Copilot, and local LLMs to:

• Scene Management: Create, modify, and organize GameObjects in scenes
• Asset Operations: Manage materials, textures, prefabs, and other assets
• Script Editing: Generate and modify C# scripts with Roslyn validation
• Testing: Run Unity Test Framework tests programmatically
• VFX & Animation: Create visual effects and animations
• UI Development: Build UI elements and interfaces
• Profiling: Analyze performance metrics

The architecture uses a dual codebase design:

• Python Server: MCP server using FastMCP that exposes tools to AI assistants via stdio or HTTP transport
• Unity Plugin: C# Editor package that receives commands and executes them in the Unity Editor

Communication happens through WebSocket connections (or legacy TCP bridge in stdio mode), with the Python server acting as an intermediary between AI clients and the Unity Editor.

MCP for Unity is a polyglot system with both Python and C# codebases:

Python Server:

• Python 3.10+ (supports up to 3.14)
• FastMCP 3.x for MCP protocol implementation
• FastAPI for HTTP transport support
• httpx for async HTTP client operations
• Pydantic 2.x for data validation
• Click for CLI interface
• uv as the recommended package manager
• pytest for testing

Unity C# Package:

• Unity Editor 2021.3 LTS or newer
• C# with Unity API integration
• Newtonsoft.Json for JSON serialization
• Unity Test Framework for testing
• UPM (Unity Package Manager) package format
• WebSocketSharp for WebSocket communication

Architecture Patterns:

• MCP tools in Server/src/services/tools/ using @mcp_for_unity_tool decorator
• CLI commands in Server/src/cli/commands/ using Click
• C# tools auto-discovered via reflection with [McpForUnityTool] attribute
• Domain-symmetric design: Python tools mirror C# Editor tools
• Async-first design with support for long-running operations

Transport Modes:

• Stdio: Single-agent, one Python process per MCP client
• HTTP: Multi-agent ready, session isolation via client_id

Before setting up MCP for Unity, ensure you have the following:

System Requirements:

• Unity Editor 2021.3 LTS or newer installed
• Python 3.10 or newer (3.11, 3.12, 3.13, 3.14 all supported)
• uv package manager (highly recommended)
• Git installed (for package installation)

AI Client Setup: You'll need an MCP-compatible AI client such as:

• Claude Desktop or Claude Code
• Cursor IDE
• VSCode with Copilot Chat
• Any MCP-compliant client

Optional:

• Docker (for containerized server deployment)
• Unity Hub for managing multiple Unity versions

Verify Python installation:

The uv package manager from Astral is the recommended way to install and run MCP for Unity. It's significantly faster than pip and provides reliable installations.

macOS/Linux:

On Windows, use PowerShell or winget to install uv:

PowerShell:

Install the MCP for Unity package into your Unity project. The package is available via Git URL, Asset Store, or OpenUPM.

Method 1: Git URL (Recommended)

In Unity Editor:

1. Go to Window → Package Manager
2. Click the + button in the top-left corner
3. Select Add package from git URL...
4. Paste one of the following URLs:

Stable version (main branch):

Beta version (beta branch): Use this for the latest features before they hit stable:

After installing the package, configure it for your AI client:

1. In Unity Editor, go to Window → MCP for Unity → Configure All Detected Clients
2. The setup wizard will guide you through:
   • Detecting available AI clients on your system
   • Configuring MCP server connections
   • Setting up automatic server startup

Manual Configuration:

If auto-detection doesn't work, you can manually configure your AI client:

Claude Desktop Configuration (~/.claude/settings.json on macOS/Linux, %APPDATA%\Claude\settings.json on Windows):

HTTP Transport (for multi-agent setups):

For scenarios where you need multiple AI clients or remote access, use HTTP transport:

1. Start the server:

1. Configure your MCP client for HTTP:

Alternative: Install from PyPI

If you prefer not to use uvx, you can install the package directly:

For development/contribution:

Clone the repository and run from source:

Docker deployment:

For containerized deployments or testing:

Use pre-built image:

Build locally:

After setup, test your connection with a simple prompt in your AI client:

Example prompts to try:

MCP for Unity organizes tools into groups. Only the core group is enabled by default. Other groups can be enabled via the manage_tools command.

Available tool groups:

| Group | Description | Default | |-------|-------------|---------| | core | Basic Unity operations, scene management | ✅ Enabled | | vfx | Visual effects (ParticleSystems, Shaders) | ❌ Disabled | | animation | Animations, animation controllers | ❌ Disabled | | ui | UI elements (Canvas, Text, Buttons) | ❌ Disabled | | scripting_ext | Script generation with Roslyn | ❌ Disabled | | testing | Test Framework integration | ❌ Disabled | | probuilder | ProBuilder mesh generation | ❌ Disabled | | profiling | Unity profiler integration | ❌ Disabled | | docs | Documentation and help | ✅ Enabled |

Enable additional tool groups:

You can enable tool groups by using the manage_tools tool in your AI assistant conversation, or through the Unity Editor settings.

Here's a practical example of using MCP for Unity to create objects in your scene:

Basic example - Create cubes:

Advanced example - Create scripts with Roslyn validation:

First, enable the scripting_ext tool group, then:

Advanced: Remote-hosted server with authentication

For team deployments or Asset Store distribution, you can run the server as a remote service with API key authentication:

Server configuration:

Client configuration with API key:

MCP for Unity can be configured via environment variables:

Transport and networking:

MCP for Unity provides MCP resources for reading Unity Editor state without modifying it. These are accessed via resource URIs:

Available resources:

| Resource | URI Pattern | Description | |----------|-------------|-------------| | Editor state | mcpforunity://editor/state | Editor readiness snapshot | | Project tags | mcpforunity://project/tags | All project tags and layers | | GameObject | mcpforunity://scene/gameobject/{id} | GameObject details by instance ID | | Prefab | mcpforunity://prefab/{encoded_path} | Prefab info by asset path | | Scene list | mcpforunity://scene/list | All open scenes | | Console | mcpforunity://editor/console | Editor console messages |

Important: Always use ListMcpResources to get the current resource URIs, as the format may change between versions.

Common issues and solutions:

Issue: Server won't start

• Check Python version: python --version (must be 3.10+)
• Verify uv installation: uv --version
• Check if port 8080 is available (for HTTP mode)

Issue: Unity connection fails

• Ensure Unity Editor is running
• Check that the MCP for Unity package is installed
• Verify the package version matches the server version
• Look at Unity Editor Console for errors

Issue: Tools not available

• Check if the tool group is enabled
• Use manage_tools to enable additional groups
• Restart your AI client after enabling tools

Issue: HTTP transport issues

• Verify firewall allows localhost:8080
• Check UNITY_MCP_HTTP_ environment variables
• Ensure the URL in client config matches server URL

Logs location:

• Windows: %LOCALAPPDATA%\UnityMCP\Logs
• macOS: ~/Library/Application Support/UnityMCP/Logs
• Linux: $XDG_STATE_HOME/UnityMCP/Logs or ~/.local/state/UnityMCP/Logs

Setting up for development:

The repository has two codebases to work with:

• Server/ - Python MCP server
• MCPForUnity/ - Unity C# Editor package

Python development:

Unity testing:

Open the test project in Unity and run the Test Runner:

1. Open Unity Editor
2. File → Import Package → Custom Package
3. Select TestProjects/UnityMCPTests folder from the repository
4. Or open TestProjects/UnityMCPTests directly in Unity
5. Window → Testing → Test Runner
6. Run tests to verify functionality

Local Unity version testing: Use the provided script to test across Unity versions:

tools/check-unity-versions.sh       # compile-only
tools/check-unity-versions.sh --full # full test run

Official documentation and community:

• 📖 Documentation
• 💬 Discord Community
• 🐛 Report Issues
• 💡 Discussions
• 📄 Contributing Guide
• 🔒 Security Policy
• 📝 License - MIT

Related projects:

• Aura for Unity - Premium Unity/Unreal AI assistant
• Godot AI - MCP for Godot Engine

Research citation: If MCP for Unity helped your research, please cite it:

@inproceedings{wu2025mcpunity,
  author    = {Wu, Shutong and Barnett, Justin P.},
  title     = {{MCP-Unity}: {Protocol-Driven} Framework for Interactive {3D} Authoring},
  year      = {2025},
  publisher = {Association for Computing Machinery},
  doi       = {10.1145/3757376.3771417},
  series    = {SA Technical Communications '25}
}