Troubleshooting
Server Not Starting
Check the Unity Console for
[MCP]log entriesEnsure port 18711 is not blocked by a firewall or another application
Toggle Debug mode via the toolbar popup for verbose logging
Try clicking Restart Python Server in the setup popup
Tools Not Discovered
Ensure methods are
public static stringwith the[McpTool]attributeCheck for compile errors in the Unity Console — tools are only registered after successful compilation
Click Refresh in the toolbar popup to force re-discovery
Verify the tool class is in an assembly that references
realvirtual.MCP
Connection Issues
The brain icon should be green when a client is connected
Yellow means the server is running but no client has connected yet
Check that your MCP client configuration points to the correct Python server path
Ensure git is installed and available in PATH
Timeouts During Play Mode
Unity throttles editor updates during play mode — tool calls may be slower
component_setoperations may not work during play modecomponent_getcan timeout if the Unity main thread is busy with simulationConsider stopping simulation before performing editor operations
Python Server Issues
Click Update Python Server (git pull) to get the latest version
Click Open MCP Folder to inspect the Python server files
The Python server includes an embedded Python 3.12 runtime — no system Python is required
Check the Python server console output for connection errors
Port Conflicts
The MCP Server uses port 18711 by default. If the port is busy, it auto-increments to find a free port. The actual port is shown in the toolbar popup. Ensure your MCP client configuration matches the displayed port.
Multi-Instance Setup
Each Unity instance gets a unique instance hash (shown as #xxxxxxxx in the toolbar). When running multiple Unity projects simultaneously, each instance runs its own MCP server on a different port. The Python server uses the instance hash to connect to the correct Unity instance.
Last updated