Plugin Troubleshooting

​

Solution

1. Verify MCP server is installed:
   claude mcp list
   
   You should see robloxstudio-mcp in the list
2. Restart your AI assistant (Claude Code, Claude Desktop, etc.)
   • The MCP server starts automatically when the AI assistant launches
3. Click the “MCP Server” button in the Plugins toolbar to activate
4. Check the status steps in the plugin dock widget:
   • Step 1 should show “HTTP server reachable (OK)”
   • Step 2 should show “MCP bridge connected (OK)”
   • Step 3 should show “Ready for commands (OK)”

​

Solution

1. Open Game Settings:
   • Home → Settings → Game Settings
2. Navigate to Security tab
3. Enable “Allow HTTP Requests”
4. Restart the plugin:
   • Click the “MCP Server” button twice (off then on)

​

Symptoms

• “HTTP: OK MCP: …” in status
• Yellow warning indicator
• Troubleshooting tip appears in widget

​

Solution

1. Close all Node.js processes:
   • Windows: Open Task Manager → Find all node.exe → End Task
   • macOS: Activity Monitor → Search “node” → Force Quit
2. Restart your AI assistant (Claude Code, Claude Desktop, etc.)
3. Wait for connection:
   • The plugin will automatically reconnect
   • Status should change to “Connected” within 10 seconds

​

Possible Causes

• MCP server crashed or stopped
• AI assistant was closed
• Network or firewall blocking localhost

​

Solution

1. Check if AI assistant is still running
2. Check Studio Output window for error messages:
   • View → Output (or press F9)
3. Verify firewall settings:
   • Ensure localhost (127.0.0.1) connections are allowed
   • Check if antivirus is blocking Roblox Studio
4. Restart both applications:
   • Close Roblox Studio completely
   • Restart your AI assistant
   • Reopen Studio and activate plugin

​

Solution

1. Check Windows Firewall:
   • Control Panel → Windows Defender Firewall → Allow an app
   • Ensure Roblox Studio is allowed for Private networks
2. Check antivirus software:
   • Some antivirus programs block localhost HTTP connections
   • Add exception for localhost:3002 and localhost:3001
3. Test localhost connectivity:
   curl http://localhost:3002/poll
   
   Should return a JSON response (may be empty)

​

Solution

1. Verify file location:
   • Windows: %LOCALAPPDATA%/Roblox/Plugins/
   • macOS: ~/Documents/Roblox/Plugins/
   • File should be named MCPPlugin.rbxmx or similar
2. Restart Roblox Studio completely:
   • Close all Studio windows
   • Reopen Studio
3. Check the Output window (F9) for error messages:
   • Errors will appear if the plugin failed to load
4. Try alternative installation method:
   • If direct download fails, try the “Save as Local Plugin” method
   • See Installation Guide for details

​

Common Errors

• Enable “Allow HTTP Requests” in Game Settings → Security

• Plugin code may be corrupted
• Re-download from GitHub Releases

• Using wrong installation method
• Plugin should be in Plugins folder, not ServerScriptService

​

Solution

1. Check the exact error message in Output window
2. Delete the corrupted plugin:
   • Go to Plugins folder
   • Delete the plugin file
3. Reinstall using a different method:
   • Try Creator Store installation (Method 1)
   • Or re-download from GitHub (Method 2)

​

Solution

1. Check your MCP server configuration:
   • Default port is 3002
   • Some setups may use different ports
2. Update Server URL in plugin:
   • Open plugin dock widget
   • Connection Settings → Server URL
   • Change to http://localhost:YOUR_PORT
3. Verify MCP server is running on that port:
   netstat -an | grep 3002
   

​

Solution

1. Check Node.js installation:
   node --version
   
   Should show v16 or higher
2. Check npx availability:
   npx --version
   
3. Manually test MCP server:
   npx -y robloxstudio-mcp@latest
   
   Should start without errors
4. Check AI assistant logs:
   • Claude Code: Check extension logs
   • Claude Desktop: Check console output
5. Try alternative configuration:
   {
     "mcpServers": {
       "robloxstudio-mcp": {
         "command": "cmd",
         "args": ["/c", "npx", "-y", "robloxstudio-mcp@latest"]
       }
     }
   }
   

​

Possible Causes

• Large project with many objects
• Complex search queries
• Network latency

​

Solution

1. Use specific paths instead of scanning entire game:
   • Instead of asking for “all scripts”, specify a service
   • Example: “List scripts in ServerScriptService”
2. Limit search depth:
   • Use maxDepth parameter in queries
   • Avoid deep recursive searches
3. Check Activity Log:
   • Open plugin dock widget
   • Look for slow requests in the log
   • Response times shown in milliseconds
4. Monitor Studio performance:
   • View → Stats (or press F3)
   • Check CPU and memory usage

​

Solution

1. Check Activity Log frequency:
   • Excessive polling may indicate a problem
   • Should poll every 500ms when disconnected
2. Reduce log verbosity:
   • Clear the activity log regularly (X button)
   • Poll events are already throttled 10:1
3. Close plugin when not in use:
   • Click “MCP Server” button to deactivate
   • Stops all background polling
4. Check for infinite loops:
   • View Studio Output window for errors
   • Uninstall and reinstall plugin if corrupted