Create your Unity apps with LLMs!

MCP for Unity acts as a bridge, allowing AI assistants (like Claude, Cursor) to interact directly with your Unity Editor via a local MCP (Model Context Protocol) Client. Give your LLM tools to manage assets, control scenes, edit scripts, and automate tasks within Unity.

Get help, share ideas, and collaborate with other MCP for Unity developers!

• 🗣️ Natural Language Control: Instruct your LLM to perform Unity tasks.
• 🛠️ Powerful Tools: Manage assets, scenes, materials, scripts, and editor functions.
• 🤖 Automation: Automate repetitive Unity workflows.
• 🧩 Extensible: Designed to work with various MCP Clients.

MCP for Unity connects your tools using two components:

1. MCP for Unity Bridge: A Unity package running inside the Editor. (Installed via Package Manager).
2. MCP for Unity Server: A Python server that runs locally, communicating between the Unity Bridge and your MCP Client. (Installed automatically by the package on first run or via Auto-Setup; manual setup is available as a fallback).

• Python: Version 3.12 or newer. Download Python

• Unity Hub & Editor: Version 2021.3 LTS or newer. Download Unity

• uv (Python toolchain manager):

  # macOS / Linux
  curl -LsSf https://astral.sh/uv/install.sh | sh
  
  # Windows (PowerShell)
  winget install --id=astral-sh.uv  -e
  
  # Docs: https://docs.astral.sh/uv/getting-started/installation/

• An MCP Client: : Claude Desktop | Claude Code | Cursor | Visual Studio Code Copilot | Windsurf | Others work with manual config

• [Optional] Roslyn for Advanced Script Validation

  For Strict validation level that catches undefined namespaces, types, and methods:

  Method 1: NuGet for Unity (Recommended)

  1. Install NuGetForUnity
  2. Go to Window > NuGet Package Manager
  3. Search for Microsoft.CodeAnalysis, select version 4.14.0, and install the package
  4. Also install package SQLitePCLRaw.core and SQLitePCLRaw.bundle_e_sqlite3.
  5. Go to Player Settings > Scripting Define Symbols
  6. Add USE_ROSLYN
  7. Restart Unity

  Method 2: Manual DLL Installation

  1. Download Microsoft.CodeAnalysis.CSharp.dll and dependencies from NuGet
  2. Place DLLs in Assets/Plugins/ folder
  3. Ensure .NET compatibility settings are correct
  4. Add USE_ROSLYN to Scripting Define Symbols
  5. Restart Unity

  Note: Without Roslyn, script validation falls back to basic structural checks. Roslyn enables full C# compiler diagnostics with precise error reporting.

1. Open your Unity project.
2. Go to Window > Package Manager.
3. Click + -> Add package from git URL....
4. Enter:

   https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity
   

5. Click Add.
6. The MCP server is installed automatically by the package on first run or via Auto-Setup. If that fails, use Manual Configuration (below).

1. Install the OpenUPM CLI
2. Open a terminal (PowerShell, Terminal, etc.) and navigate to your Unity project directory
3. Run openupm add com.coplaydev.unity-mcp

Note: If you installed the MCP Server before Coplay's maintenance, you will need to uninstall the old package before re-installing the new one.

Connect your MCP Client (Claude, Cursor, etc.) to the Python server set up in Step 1 (auto) or via Manual Configuration (below).

Option A: Auto-Setup (Recommended for Claude/Cursor/VSC Copilot)

1. In Unity, go to Window > MCP for Unity.
2. Click Auto-Setup.
3. Look for a green status indicator 🟢 and "Connected ✓". (This attempts to modify the MCP Client's config file automatically).

Option B: Manual Configuration

If Auto-Setup fails or you use a different client:

1. Find your MCP Client's configuration file. (Check client documentation).
   • Claude Example (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json
   • Claude Example (Windows): %APPDATA%\Claude\claude_desktop_config.json
2. Edit the file to add/update the mcpServers section, using the exact paths from Step 1.

claude mcp add UnityMCP -- uv --directory /Users/USERNAME/Library/AppSupport/UnityMCP/UnityMcpServer/src run server.py

claude mcp add UnityMCP -- "C:/Users/USERNAME/AppData/Local/Microsoft/WinGet/Links/uv.exe" --directory "C:/Users/USERNAME/AppData/Local/UnityMCP/UnityMcpServer/src" run server.py

{
  "servers": {
    "unityMCP": {
      "command": "uv",
      "args": ["--directory","<ABSOLUTE_PATH_TO>/UnityMcpServer/src","run","server.py"],
      "type": "stdio"
    }
  }
}

{
  "mcpServers": {
    "UnityMCP": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "C:\\Users\\YOUR_USERNAME\\AppData\\Local\\UnityMCP\\UnityMcpServer\\src",
        "server.py"
      ]
    }
    // ... other servers might be here ...
  }
}

{
  "mcpServers": {
    "UnityMCP": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/Users/YOUR_USERNAME/Library/AppSupport/UnityMCP/UnityMcpServer/src",
        "server.py"
      ]
    }
    // ... other servers might be here ...
  }
}

{
  "mcpServers": {
    "UnityMCP": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/home/YOUR_USERNAME/.local/share/UnityMCP/UnityMcpServer/src",
        "server.py"
      ]
    }
    // ... other servers might be here ...
  }
}

1. Open your Unity Project. The MCP for Unity package should connect automatically. Check status via Window > MCP for Unity.

2. Start your MCP Client (Claude, Cursor, etc.). It should automatically launch the MCP for Unity Server (Python) using the configuration from Installation Step 2.

3. Interact! Unity tools should now be available in your MCP Client.

   Example Prompt: Create a 3D player controller, Create a tic-tac-toe game in 3D, Create a cool shader and apply to a cube.

Unity MCP now includes comprehensive Docker support for easy containerized deployment and development. This is particularly useful for:

• Running MCP server in isolated environments
• Consistent deployment across different systems
• Cloud-based Unity development workflows
• CI/CD pipelines

1. Clone and setup:

   git clone https://github.com/Ddemon26/unity-mcp.git
   cd unity-mcp
   cp .env.example .env

2. Configure environment (optional): Edit .env file to customize ports, Unity project path, and other settings.

3. Run with Docker Compose:

   # Production mode
   docker-compose up unity-mcp-server
   
   # Development mode with hot reload
   docker-compose --profile development up unity-mcp-dev

The Docker setup supports all server configuration via environment variables:

# Network settings
UNITY_HOST=host.docker.internal  # Use this for Unity on host machine
UNITY_PORT=6400
MCP_PORT=6500

# Development ports
DEV_UNITY_PORT=6401
DEV_MCP_PORT=6501

# Logging and performance
LOG_LEVEL=INFO
CONNECTION_TIMEOUT=1.0
MAX_RETRIES=10

# Telemetry (set DISABLE_TELEMETRY=true to disable)
TELEMETRY_ENABLED=true
DISABLE_TELEMETRY=false

# Unity project path (mounted as volume)
UNITY_PROJECT_PATH=./TestProjects/UnityMCPTests

# Build the image
docker build -t unity-mcp-server ./UnityMcpBridge/UnityMcpServer~/src

# Run standalone container
docker run -p 6500:6500 -e UNITY_HOST=host.docker.internal unity-mcp-server

# Development with volume mount
docker run -v $(pwd)/UnityMcpBridge/UnityMcpServer~/src:/app \
  -p 6500:6500 -e LOG_LEVEL=DEBUG unity-mcp-server

# Check container health
docker ps
docker logs unity-mcp-server

The Dockerfile supports both development and production builds:

• Development: Includes dev dependencies, volume mounts, auto-reload
• Production: Optimized image size, production settings, health checks

When Unity Editor runs on your host machine and MCP server in Docker:

1. Use UNITY_HOST=host.docker.internal (Windows/Mac) or UNITY_HOST=172.17.0.1 (Linux)
2. Ensure Unity project is accessible via volume mounts
3. Configure Unity MCP plugin to connect to the containerized server

Connection Issues:

• Verify UNITY_HOST points to your host machine from container
• Check firewall settings for Unity and MCP ports
• Ensure Unity MCP plugin is configured with correct container ports

Performance:

• Adjust BUFFER_SIZE and timeout settings in .env
• Monitor container resources with docker stats
• Use development profile for debugging with verbose logging

📖 See DOCKER.md for complete Docker implementation details and advanced configuration options.

MCP for Unity uses a Python MCP Server tied with Unity's C# scripts for tools. If you'd like to extend the functionality with your own tools, learn how to do so in CUSTOM_TOOLS.md.

If you're contributing to MCP for Unity or want to test core changes, we have development tools to streamline your workflow:

• Development Deployment Scripts: Quickly deploy and test your changes to MCP for Unity Bridge and Python Server
• Automatic Backup System: Safe testing with easy rollback capabilities
• Hot Reload Workflow: Fast iteration cycle for core development

📖 See README-DEV.md for complete development setup and workflow documentation.

Help make MCP for Unity better!

1. Fork the main repository.
2. Create a branch (feature/your-idea or bugfix/your-fix).
3. Make changes.
4. Commit (feat: Add cool new feature).
5. Push your branch.
6. Open a Pull Request against the main branch.

MCP for Unity includes privacy-focused, anonymous telemetry to help us improve the product. We collect usage analytics and performance data, but never your code, project names, or personal information.

• 🔒 Anonymous: Random UUIDs only, no personal data
• 🚫 Easy opt-out: Set DISABLE_TELEMETRY=true environment variable
• 📖 Transparent: See TELEMETRY.md for full details

Your privacy matters to us. All telemetry is optional and designed to respect your workflow.

Still stuck? Open an Issue or Join the Discord!

MIT License. See LICENSE file.

Coplay offers 2 AI tools for Unity

• MCP for Unity is available freely under the MIT license.
• Coplay is a premium Unity AI assistant that sits within Unity and is more than the MCP for Unity.

(These tools have different tech stacks. See this blog post comparing Coplay to MCP for Unity.)

This project is a free and open-source tool for the Unity Editor, and is not affiliated with Unity Technologies.