Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Chrrxs/robloxstudio-mcp/llms.txt

Use this file to discover all available pages before exploring further.

Most Roblox Studio MCP issues fall into a handful of categories: the Studio plugin is not loaded or not connected, an HTTP permission is missing, the plugin and server versions are out of sync, or tool calls are being routed to the wrong place when multiple Studio windows are open. The entries below cover every known failure mode and how to resolve each one.
A red or Disconnected status in the plugin toolbar widget is normal behavior when the MCP server is not running. The plugin polls localhost:58741 on a 500 ms interval and updates its indicator as soon as a server appears.Steps to resolve:
  1. Verify the MCP server process is running. Check your terminal or AI client for the server process. If you are using an MCP client like Claude Desktop, confirm the server entry is present and the client has connected to it.
  2. Check whether another process is occupying port 58741. On macOS/Linux: lsof -i :58741. On Windows: netstat -ano | findstr :58741. If another process holds the port, stop it and restart the MCP server.
  3. If the port is free and the server is running but the plugin still shows Disconnected, check the Studio Output window for error messages from the plugin.
  4. Confirm “Allow HTTP Requests” is enabled in Game Settings → Security (see the HTTP 403 entry below).
HTTP 403 responses from the plugin indicate that Roblox Studio is blocking outbound HTTP calls to localhost.Fix: Enable Allow HTTP Requests in Game Settings → Security.
  1. Open your place in Studio.
  2. Click Home → Game Settings.
  3. Go to the Security tab.
  4. Enable the Allow HTTP Requests toggle.
  5. Save and reopen the place if prompted.
This setting must be enabled for every place you open with the plugin. It is stored per-place in HttpService.HttpEnabled.
If the plugin widget or button does not appear after installation:
  1. Verify the .rbxmx file is in the correct Plugins folder. The default paths are:
    • Windows: %LOCALAPPDATA%\Roblox\Plugins\
    • macOS: ~/Documents/Roblox/Plugins/
    • WSL: /mnt/c/Users/<you>/AppData/Local/Roblox/Plugins/
  2. Fully close and reopen Studio. Plugin files are only loaded at Studio startup. A Studio window that was open when the file was copied will not pick it up until restart.
  3. Check the Studio Output window for errors. Open View → Output and look for any errors mentioning the plugin file or a Lua syntax problem.
  4. Confirm you have only one plugin variant installed. See the “Both plugin variants installed” entry below.
A yellow banner in the plugin widget means the Studio plugin version and the MCP server version do not match. The connection still works — all tools remain usable — but some newer features added in the mismatched version may behave unexpectedly or return errors.Fix:
  1. Restart the MCP server with --auto-install-plugin. This copies the plugin bundled with the current server package into the Plugins folder.
  2. Fully close and reopen Roblox Studio so it loads the updated .rbxmx file.
After Studio restarts, get_connected_instances should report versionMismatch: false.
The /health and /status endpoints also report pluginVersion, serverVersion, and versionMismatch if you want to check programmatically.
When more than one Studio place is connected to the same MCP server, tool calls without an explicit instance_id return a routing error because the server cannot determine which place to target.Fix: Call get_connected_instances to list all connected places and their IDs, then include instance_id in every subsequent tool call to route it to the correct place.
get_connected_instances
# Returns: [{ instance_id: "abc123", placeName: "MyGame", ... }, ...]

get_file_tree instance_id="abc123"
For multiple open Studio places, connect each plugin to the same MCP server URL (the default http://localhost:58741). Do not try to run separate MCP server processes on different ports — that model is not supported.
eval_server_runtime and eval_client_runtime require an active playtest. The runtime eval bridges are created inside the play DataModel when a playtest starts; they do not exist in edit mode.Fix: Check playtest status first, then start one if needed:
solo_playtest action="status"
# If not running:
solo_playtest action="start" mode="play"
Both tools also work with playtests started manually via the Studio Play button — the runtime bridge is created automatically inside the play DataModel regardless of how the playtest was started.
If eval_server_runtime returns a message similar to "Requested module experienced an error while loading", this is Roblox’s require() system wrapping the actual error. The real error text is preserved inside the message string.What to do: Read the full error message carefully. The actual error — a nil dereference, a parser error, a nested require() failure — appears in the body of the wrapper message. Do not retry the call blindly; fix the underlying issue first.This behavior is tested explicitly in the integration suite (eval-bridge-error-preservation.mjs) to ensure the MCP bridge does not swallow the inner error.
Installing both MCPPlugin.rbxmx and MCPInspectorPlugin.rbxmx in the Plugins folder at the same time causes Studio to load both. The two plugins register duplicate runtime peers and can produce confusing behavior including double log entries and ambiguous peer routing.Fix: Remove one variant. Keep only the file matching the package you are running:
  • @chrrxs/robloxstudio-mcp → keep MCPPlugin.rbxmx, remove MCPInspectorPlugin.rbxmx
  • @chrrxs/robloxstudio-mcp-inspector → keep MCPInspectorPlugin.rbxmx, remove MCPPlugin.rbxmx
The CLI installers (--install-plugin, --auto-install-plugin) automatically remove the other variant before installing, so this situation typically only arises from a manual file copy.Fully close and reopen Studio after removing the extra file.
On some Windows machines, the MCP client process cannot find npx in its environment even though it is installed.Fix: Use the cmd /c wrapper in your MCP client JSON config:
{
  "mcpServers": {
    "robloxstudio-mcp": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@chrrxs/robloxstudio-mcp@latest", "--auto-install-plugin"]
    }
  }
}
This invokes npx through cmd.exe, which resolves the full PATH correctly.
When running the MCP server inside WSL, --auto-install-plugin targets /mnt/c/Users/<you>/AppData/Local/Roblox/Plugins/ by default, mapping to the Windows Roblox Plugins folder through the WSL filesystem bridge.If your Windows username contains spaces or your Roblox installation is in a non-default location, the auto-detected path may be wrong.Fix: Set MCP_PLUGINS_DIR to the correct path before starting the server:
MCP_PLUGINS_DIR="/mnt/d/Games/Roblox/Plugins" npx -y @chrrxs/robloxstudio-mcp@latest --auto-install-plugin
Or add it to the env block in your MCP client config:
{
  "mcpServers": {
    "robloxstudio-mcp": {
      "command": "npx",
      "args": ["-y", "@chrrxs/robloxstudio-mcp@latest", "--auto-install-plugin"],
      "env": {
        "MCP_PLUGINS_DIR": "/mnt/d/Games/Roblox/Plugins"
      }
    }
  }
}
If the MCP server fails to start with an EADDRINUSE or similar error, another process is already bound to port 58741.Identify the occupying process:
# macOS / Linux
lsof -i :58741

# Windows (PowerShell)
netstat -ano | findstr :58741
Stop the conflicting process, then restart the MCP server. If the port is occupied by a stale MCP server instance from a previous session, kill that process and retry.
Port configuration is not currently supported. If you need a configurable port, file an issue on the project repository.

Build docs developers (and LLMs) love

Get started for freeTalk to us