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 exposes three tools for running Luau code against a connected Studio place. They differ in one critical dimension: which Lua VM the code runs in. execute_luau always runs inside the Studio plugin’s own thread, which carries PluginSecurity permissions and a separate require cache from your game scripts. eval_server_runtime and eval_client_runtime run directly inside the running game’s Script and LocalScript VMs respectively, sharing the same require cache as your live game code. Choosing the right tool determines whether you see real game state or a plugin-context snapshot of it.

​
execute_luau

Executes Luau code in the Studio plugin context. The code always runs with PluginSecurity permissions, regardless of the target. When target="server" or target="client-N" is set, the code runs against the live runtime DataModel (so game.Workspace and services reflect live state) but it is not executed in the game’s Script VM — it still runs in the plugin thread with no access to the game’s require cache. Use print() and warn() for output. Return values are captured and returned to the MCP caller. When to use: Inspecting and modifying instance properties, calling Plugin APIs, reading DataModel state in the edit context, or performing non-game-logic tasks that need PluginSecurity (e.g. ChangeHistoryService, Selection, Plugin).
​
code
string
required
Luau code to execute. Use print() or warn() to emit output. Returned values from the top level are captured.
​
target
string
DataModel to run code against. "edit" (default) targets the edit DataModel. "server" and "client-1", "client-2", etc. target live runtime DataModels during a playtest, but execution still occurs in plugin context.
​
instance_id
string
Which connected Studio place to target. Required when multiple places are connected; omit when only one is open. Use get_connected_instances to list available IDs.

​
Example — read an instance property

-- Read the CFrame of a part in the edit DataModel
local part = game.Workspace:FindFirstChild("SpawnPlatform")
if part then
    return tostring(part.CFrame)
end
return "Part not found"
When using target="server" or target="client-N", the code runs against the live runtime DataModel (you see live positions, values, etc.) but in plugin context. If you need to call require() on a module that game scripts have already loaded, use eval_server_runtime or eval_client_runtime instead.

​
eval_server_runtime

Executes Luau code inside the running game’s Server Script VM. This is fundamentally different from execute_luau target="server": the code runs in the same Lua environment as your Script instances, shares the require() module cache with all server scripts currently loaded, and has access to values stored in module-level upvalues. A runtime bridge is created automatically inside the play DataModel, including for playtests started manually via the Studio Play button — no extra setup is required. Use return ... to get a value back. When to use: Inspecting live game state (player data, active rounds, module-level singletons), calling game services, debugging game logic that only exists in the Server Script VM.
​
code
string
required
Luau code to execute in the server Script VM. Use return ... to return a value to the MCP caller.
​
instance_id
string
Which connected Studio place to target. Required when multiple places are connected; omit when only one is open.
Requires a running playtest. If no playtest is active, the tool returns an error. Start a playtest first with solo_playtest or multiplayer_playtest.

​
Example — inspect a live server module singleton

-- Reach into a live module singleton that game scripts have already required
local MatchService = require(game.ServerScriptService.MatchService)
return MatchService.activeMatches

-- Check how many players are currently in a round
local RoundManager = require(game.ServerScriptService.RoundManager)
return {
    phase = RoundManager.currentPhase,
    playerCount = #RoundManager.activePlayers,
    elapsed = os.clock() - RoundManager.roundStartTime
}
Because eval_server_runtime shares the live require() cache, the module you require() here is the exact same table your game scripts are mutating. You can read and write module-level state directly, which is the fastest way to inspect or patch a running game without modifying source.

​
eval_client_runtime

Executes Luau code inside a running game client’s LocalScript VM. Like eval_server_runtime, this runs inside the actual game VM (not plugin context) and shares the require() cache with LocalScript and ModuleScript instances loaded on that client. Use return ... to get a value back. When to use: Inspecting client-side state — PlayerGui, LocalPlayer, StarterPlayerScripts module singletons, local variables, HUD state, or any client-only logic.
​
code
string
required
Luau code to execute in the client LocalScript VM. Use return ... to return a value.
​
target
string
Which client to target. "client-1" (default), "client-2", etc. for multiplayer tests. Use get_connected_instances to see available client roles.
​
instance_id
string
Which connected Studio place to target. Required when multiple places are connected; omit when only one is open.
Requires a running playtest. If no playtest is active, the tool returns an error.

​
Example — read client-side player state

-- Read the LocalPlayer's health and position on client-1
local player = game.Players.LocalPlayer
local character = player.Character
if not character then
    return { error = "No character spawned" }
end
local humanoid = character:FindFirstChild("Humanoid")
local rootPart = character:FindFirstChild("HumanoidRootPart")
return {
    health = humanoid and humanoid.Health or 0,
    maxHealth = humanoid and humanoid.MaxHealth or 0,
    position = rootPart and tostring(rootPart.Position) or "unknown"
}

-- Inspect a client-side UI module singleton
local HUDController = require(game.StarterPlayer.StarterPlayerScripts.HUDController)
return {
    visible = HUDController.isVisible,
    currentScreen = HUDController.activeScreen
}

​
Plugin context vs. game Script VM — side-by-side

Understanding this distinction is essential when debugging game logic:
execute_luaueval_server_runtimeeval_client_runtime
VMPlugin thread (PluginSecurity)Game Server Script VMGame Client LocalScript VM
require() cachePlugin’s own cacheShared with game server scriptsShared with game client scripts
Sees live module state?No (separate cache)YesYes
PluginSecurity APIs?YesNoNo
Requires playtest?No (target="edit")YesYes
target param?Yes (edit/server/client-N)No (always server)Yes (client-1, client-2, …)
When you call execute_luau with target="server", you can read instance properties of live DataModel objects (positions, values, etc.) but you cannot reach into module-level upvalues or singletons that game scripts have populated — because your code runs in the plugin’s separate require() environment. Use eval_server_runtime for that.

Build docs developers (and LLMs) love

Get started for freeTalk to us