Skip to content

Troubleshooting

Jump to bottom
Ivan Murzak edited this page Mar 9, 2026 · 3 revisions

Troubleshooting Guide

This guide covers real issues you may encounter with Unity-MCP and how to resolve them.

Quick Checklist

If Unity-MCP is not working at all:

  1. Check the Unity Console for error messages
  2. Verify the plugin is installed: open Window > AI Game Developer
  3. Check the connection status in the plugin window
  4. Restart Unity Editor

Connection Issues (Plugin to Server)

Unity-MCP uses SignalR for communication between the plugin and the MCP server. The server binary is auto-downloaded and auto-started by the plugin.

Server Not Starting

The plugin automatically downloads the server binary to Library/mcp-server/{platform}/ (where platform is win-x64, osx-x64, or linux-x64) and starts it on Unity Editor load.

Check for the server binary:

  • Look in your Unity project at Library/mcp-server/ for the platform-specific folder
  • If missing, the plugin may have failed to download it; check the Unity Console for download errors

Check the Unity Console for error messages related to McpServerManager. Common issues:

  • Network failure during binary download
  • File permission issues preventing extraction
  • Antivirus software blocking the server executable

Project path contains spaces: Unity-MCP validates the project path on startup. If your project path contains spaces, you will see a warning. Move your project to a path without spaces.

Port Conflicts

Unity-MCP uses a deterministic port based on the SHA256 hash of your Unity project path, mapped to the range 50000-59999. This means the same project always uses the same port, and different projects use different ports.

If another process is using that port:

  • The plugin detects an external server on the port and enters External mode
  • Check what process is using the port: 
    # Windows
netstat -ano | findstr :<port>

# macOS/Linux
lsof -i :<port>
  • Close the conflicting process, or move your Unity project to a different directory (which changes the port)

SignalR Connection Failures

If the plugin shows a disconnected state:

  • The server may have crashed; check Library/mcp-server/ for log files
  • The plugin reconnects automatically on domain reload and play mode transitions
  • Try closing and reopening Unity

AI Client Not Connecting

The AI client (Claude Desktop, Cursor, VS Code Copilot, etc.) connects to the MCP server via stdio or streamableHttp transport. The server bridges this connection to the Unity plugin via SignalR.

Verify Configuration

  1. Open Window > AI Game Developer in Unity
  2. Select your AI client's configurator tab
  3. Click the configure button to generate or update the AI client's config file
  4. Restart your AI client after configuration changes

The plugin configuration is stored at:

Assets/Resources/AI-Game-Developer-Config.json

Supported AI Clients

Unity-MCP includes built-in configurators for 14 AI clients:

Client Configurator
Antigravity AntigravityConfigurator
Claude Code ClaudeCodeConfigurator
Claude Desktop ClaudeDesktopConfigurator
Codex CodexConfigurator
Cursor CursorConfigurator
Gemini GeminiConfigurator
GitHub Copilot CLI GitHubCopilotCliConfigurator
KiloCode KiloCodeConfigurator
OpenCode OpenCodeConfigurator
Rider RiderConfigurator
UnityAi UnityAiConfigurator
VS Code Copilot VisualStudioCodeCopilotConfigurator
VS Copilot VisualStudioCopilotConfigurator
Custom CustomConfigurator

AI Client Cannot See Unity Tools

If your AI client reports no Unity tools are available:

  1. Verify the MCP server is running (check the status in Window > AI Game Developer)
  2. Ensure the AI client config file points to the correct server binary path
  3. Restart the AI client completely (not just reload)
  4. Check that the server binary exists at Library/mcp-server/{platform}/

Unity Version Compatibility

Unity-MCP requires Unity 2022.3 or newer. If you are on an older version, the plugin will not compile. Update your Unity installation via Unity Hub.

Main Thread Errors

All Unity API calls must run on the main thread. The plugin handles this internally via MainThread.Instance.Run() and MainThread.Instance.RunAsync(). If you see errors about accessing Unity API from a background thread, this indicates a bug in a custom tool implementation. Wrap all Unity API calls in MainThread.Instance.Run(() => { ... }).

Tool Execution Errors

Tools return strings prefixed with [Success] or [Error] for structured feedback to the AI client.

Common tool errors:

  • GameObject not found: The referenced GameObject does not exist in the current scene. Verify the name or path.
  • Asset not found: The asset path is incorrect. Asset paths must be relative to the project root (e.g., Assets/Materials/MyMaterial.mat).
  • Component not found: The component type name may be incorrect. Use the exact C# class name (e.g., Rigidbody, MeshRenderer, BoxCollider).
  • Scene not loaded: The target scene is not currently open. Use scene-open to load it first.

Domain Reload and Play Mode

Unity-MCP disconnects before a domain reload and reconnects afterward. When entering or exiting Play mode, a delayed reconnection is triggered. Brief disconnections during these transitions are normal.

Complete Reset

If nothing else works:

  1. Close Unity Editor
  2. Delete Library/mcp-server/ in your project directory
  3. Reopen Unity -- the plugin will re-download the server binary
  4. Open Window > AI Game Developer and reconfigure your AI client
  5. Restart your AI client

Getting Help

Before filing an issue:

  1. Note your Unity version, OS, and Unity-MCP version (current: 0.51.4)
  2. Copy the full error from the Unity Console
  3. Check existing issues on GitHub

File a bug report at GitHub Issues with the above information and steps to reproduce.

Clone this wiki locally