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.

Roblox Studio MCP ships as two distinct npm packages, each bundling a different Roblox Studio plugin file. The Full Edition gives an AI agent complete control over a live Studio session — reading, writing, scripting, playtesting, and asset management. The Inspector Edition is a safety-first alternative that exposes only read-only tools, making it suitable for code review, debugging sessions, and exploration where you want confidence that the AI cannot accidentally modify your place. Both editions share the same HTTP bridge and routing infrastructure; only the advertised tool set and the plugin file differ.

​
Comparison

Full EditionInspector Edition
npm package@chrrxs/robloxstudio-mcp@chrrxs/robloxstudio-mcp-inspector
Plugin fileMCPPlugin.rbxmxMCPInspectorPlugin.rbxmx
Advertised tools8038
Write access✅ Full — create, delete, edit scripts, set properties, attributes, tags❌ None — read-only tools only
Script editing✅ set_script_source, edit_script_lines, insert/delete_script_lines❌
Luau execution✅ execute_luau, eval_server_runtime, eval_client_runtime❌
Playtest control✅ solo_playtest, multiplayer_playtest❌
Instance creation/deletion✅ create_object, delete_object, mass_create_objects❌
Asset upload/insert✅ upload_asset, insert_asset, generate_model❌
Browsing & inspection✅✅
Script reading✅✅
Log reading✅✅
Profiler captures✅✅
Viewport screenshots✅✅
Use casesFull development, bulk refactors, playtest automation, asset workflowsCode review, debugging, exploration, on-call inspection

​
Full Edition (@chrrxs/robloxstudio-mcp)

The Full Edition is the default choice for development workflows. It exposes all 80 tools across every capability area: file tree inspection, mass property reads and writes, script search-and-replace, attribute and tag management, instance creation and deletion, Luau execution in plugin and runtime VM contexts, playtest lifecycle control, log capture, Script Profiler and MicroProfiler captures, viewport screenshots, mouse and keyboard simulation, memory analysis, Scene Analysis, .rbxm import/export, asset search and upload, AI model generation, and Studio instance management. 
# Claude Code — full edition with auto plugin install
claude mcp add robloxstudio -- npx -y @chrrxs/robloxstudio-mcp@latest --auto-install-plugin

# Manual plugin install only
npx -y @chrrxs/robloxstudio-mcp@latest --install-plugin
The entry point in packages/robloxstudio-mcp/src/index.ts initializes the server with getAllTools() and getAllCallableTools() from the core package — these return the complete TOOL_DEFINITIONS array and the callable subset (which excludes deprecated tool names from tools/list while keeping them dispatchable).

​
Inspector Edition (@chrrxs/robloxstudio-mcp-inspector)

The Inspector Edition is purpose-built for sessions where safety matters more than capability. Its entry point in packages/robloxstudio-mcp-inspector/src/index.ts initializes the server with getReadOnlyTools() and getReadOnlyCallableTools(), which filter TOOL_DEFINITIONS to only the 38 tools that carry category: 'read'. 
# Claude Code — inspector edition with auto plugin install
claude mcp add robloxstudio-inspector -- npx -y @chrrxs/robloxstudio-mcp-inspector@latest --auto-install-plugin

# Codex
codex mcp add robloxstudio-inspector -- npx -y @chrrxs/robloxstudio-mcp-inspector@latest --auto-install-plugin

# Gemini
gemini mcp add robloxstudio-inspector npx --trust -- -y @chrrxs/robloxstudio-mcp-inspector@latest --auto-install-plugin

# Manual plugin install only
npx -y @chrrxs/robloxstudio-mcp-inspector@latest --install-plugin

​
What category: 'read' Means

Every entry in TOOL_DEFINITIONS (in packages/core/src/tools/definitions.ts) carries a category field typed as 'read' | 'write'. Read-category tools are queries that return information without modifying any Studio state: 
// From definitions.ts
export type ToolCategory = 'read' | 'write';

export interface ToolDefinition {
  name: string;
  description: string;
  category: ToolCategory;   // 'read' for Inspector-safe tools
  inputSchema: object;
}
The getReadOnlyTools() function is a simple filter: 
// Conceptually equivalent to:
const readOnlyTools = TOOL_DEFINITIONS.filter(t => t.category === 'read');
Tools in the read category include browsing (get_file_tree, get_project_structure, search_files), inspection (get_instance_properties, get_instance_children, search_by_property), script reading (get_script_source, grep_scripts), attribute and tag queries (get_attributes, get_tags, get_tagged), runtime log reading (get_runtime_logs), profiler captures (capture_script_profiler, capture_micro_profiler), screenshots (capture_screenshot), asset queries (search_assets, get_asset_details, get_asset_thumbnail, preview_asset), simulation state inspection (get_simulation_state, get_device_simulator_state), build library reads (list_library, get_build, export_build), and instance listing (get_connected_instances, get_selection, get_place_info, get_services, get_class_info).
capture_script_profiler and capture_micro_profiler are category: 'read' because they observe a running session without modifying DataModel state. They are available in both editions.

​
Critical Rule: Never Install Both Variants Simultaneously

Do not leave both MCPPlugin.rbxmx and MCPInspectorPlugin.rbxmx in your Studio Plugins folder at the same time. Studio loads every .rbxmx file in the folder on startup, so both plugins will be active simultaneously. Each plugin registers its own edit/server/client peers with the bridge, creating duplicate (instanceId, role) tuples. The second registration attempt is rejected with duplicate_instance_role, and one of the two plugins will receive no work while still polling — causing confusing routing failures and missed tool calls.
The CLI installers handle this automatically: when --install-plugin or --auto-install-plugin is run for either package, it removes the other variant from the Plugins folder before copying the new one. Manual installations and custom MCP_PLUGINS_DIR paths must be managed by hand.

​
Checking for Duplicate Plugins

If you suspect both variants are installed, check your Plugins folder: 
%LOCALAPPDATA%\Roblox\Plugins\
Look for both MCPPlugin.rbxmx and MCPInspectorPlugin.rbxmx. Delete whichever you do not want.

​
Switching Between Variants

1

Fully close Studio

Studio locks plugin files while running. Ensure all Studio windows are closed before switching.
2

Run the installer for the target variant

The installer removes the opposite variant automatically.
# Switch to Full Edition
npx -y @chrrxs/robloxstudio-mcp@latest --install-plugin

# Switch to Inspector Edition
npx -y @chrrxs/robloxstudio-mcp-inspector@latest --install-plugin
To use a non-standard Plugins folder, set MCP_PLUGINS_DIR first:
MCP_PLUGINS_DIR=/custom/path npx -y @chrrxs/robloxstudio-mcp@latest --install-plugin
3

Update your MCP client configuration

If your AI client is configured to launch a specific package, update the command to match the new variant. For example, in Claude Desktop’s claude_desktop_config.json:
{
  "mcpServers": {
    "robloxstudio": {
      "command": "npx",
      "args": ["-y", "@chrrxs/robloxstudio-mcp-inspector@latest", "--auto-install-plugin"]
    }
  }
}
4

Reopen Studio

Fully close and reopen Studio. The plugin toolbar button should reflect the new variant. The server log will show the pluginVariant field ("full" or "inspector") when the plugin connects.
You can verify which variant is active after connecting by calling get_connected_instances. Each entry in the response includes a pluginVariant field ("full" or "inspector").

Build docs developers (and LLMs) love

Get started for freeTalk to us