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 that bridge visual and interactive testing inside a live playtest: capture_screenshot captures the Studio viewport at native resolution and returns it as an image; simulate_mouse_input fires real UserInputService mouse events at viewport coordinates; and simulate_keyboard_input drives the game’s input pipeline with keystrokes, held keys, or typed text. The screenshot and the input coordinate space are intentionally aligned — read click positions directly off the captured image and pass them straight to simulate_mouse_input without any coordinate translation.

​
capture_screenshot

Captures the Roblox Studio viewport at native resolution and returns it as an image along with the exact pixel dimensions. In Edit mode the viewport is captured as-is. During a regular playtest the tool auto-detects the running client and captures the live play viewport.
​
format
string
Image format:
  • "jpeg" (default) — compact and sharp at high quality. Good for most UI and 3D scene captures.
  • "png" — lossless. Best for reading dense text or fine UI elements; may be significantly larger for complex 3D scenes.
​
quality
number
JPEG quality 1–100 (default 92). Higher values produce sharper text and larger files. Ignored when format="png".
​
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.
Requirements:
  • The EditableImage API must be enabled: Game Settings → Security → Allow Mesh / Image APIs.
  • The Studio window must be visible (not minimized).
  • StudioTestService multiplayer client screenshots are currently blocked by Roblox temporary-texture process scoping. The tool returns a clear error in that case.
The returned image is never downscaled — its pixel grid exactly matches the coordinate space that simulate_mouse_input uses. Take a screenshot first, read the click position from the image, then pass those coordinates directly to simulate_mouse_input. Enlarging the Studio window raises the effective resolution if you need finer detail.

​
simulate_mouse_input

Simulates a mouse event in the running game via UserInputService:CreateVirtualInput. Fires real UserInputService input, activates GUI buttons, and interacts with 3D objects. Only works during a playtest.
​
action
string
required
Mouse action:
  • "click" — executes mouseDown + a short delay + mouseUp.
  • "mouseDown" — mouse button down only.
  • "mouseUp" — mouse button up only.
​
x
number
required
Viewport pixel X coordinate, as seen in capture_screenshot. Top-left of the viewport is (0, 0).
​
y
number
required
Viewport pixel Y coordinate, as seen in capture_screenshot.
​
button
string
Mouse button to use: "Left" (default), "Right", or "Middle".
​
target
string
Instance target. Defaults to the running playtest client ("client-1") when present, otherwise "edit". Override with "client-2", etc. for multiplayer tests.
​
instance_id
string
Which connected Studio place to target.
Only click, mouseDown, and mouseUp are supported. The UserInputService:CreateVirtualInput API has no mouse-move or scroll support.

​
simulate_keyboard_input

Simulates keyboard input in the running game via UserInputService:CreateVirtualInput. Drives the real input pipeline so game scripts, character control modules, and ContextActionService bindings all respond. Only works during a playtest.
​
keyCode
string
Enum.KeyCode name to press. Examples: "W", "A", "S", "D" (movement), "Space" (jump), "E" (interact), "F", "LeftShift", "LeftControl", "Return", "Tab", "Escape", "One", "Two", etc. Omit if using text instead.
​
action
string
Key action:
  • "tap" (default) — press + brief wait + release. Use duration to control how long the key is held.
  • "press" — key down only. Pair with "release" for sustained input like walking.
  • "release" — key up only.
​
duration
number
Hold duration in seconds for the "tap" action (default 0.1). Use longer values for sustained input — for example, duration=2 to walk forward for 2 seconds.
​
text
string
Type this string into the currently focused TextBox via SendTextInput. When provided, keyCode and action are ignored. Use this to fill in search boxes, chat inputs, or other text fields without pressing individual keys.
​
target
string
Instance target. Defaults to the running playtest client ("client-1") when present, otherwise "edit". Override with "client-2", etc.
​
instance_id
string
Which connected Studio place to target.

​
Use cases

​
Capturing a before/after visual comparison

Take a screenshot before and after a visual change to confirm it rendered correctly: 
-- 1. Capture the current state
-- capture_screenshot: { format: "png" }

-- 2. Apply your change (e.g. set_property or eval_server_runtime)
-- eval_server_runtime: { code: "game.Lighting.Brightness = 2" }

-- 3. Wait a moment for the render to update, then capture again
-- capture_screenshot: { format: "png" }

​
Clicking a UI button during a playtest

Read the button position from a screenshot and click it:
1

Take a screenshot

Call capture_screenshot to get the current viewport. Inspect the returned image for the pixel coordinates of the button.
2

Click the button

Call simulate_mouse_input with action="click" and the x/y pixel coordinates from the screenshot. The click fires real UserInputService events and activates GuiButton instances.
3

Verify the result

Call capture_screenshot again or eval_client_runtime to confirm the button action took effect.

​
Reproducing a movement scenario during debugging

Walk the character forward for 2 seconds, then jump: 
-- simulate_keyboard_input: { keyCode: "W", action: "tap", duration: 2 }
-- simulate_keyboard_input: { keyCode: "Space", action: "tap" }
For more complex movement, use separate press and release calls to hold multiple keys simultaneously: 
-- Hold W (forward) and LeftShift (sprint) together:
-- simulate_keyboard_input: { keyCode: "LeftShift", action: "press" }
-- simulate_keyboard_input: { keyCode: "W", action: "tap", duration: 3 }
-- simulate_keyboard_input: { keyCode: "LeftShift", action: "release" }

​
Typing into a TextBox

Focus the TextBox first (click it with simulate_mouse_input), then type: 
-- simulate_mouse_input: { action: "click", x: 640, y: 400 }
-- simulate_keyboard_input: { text: "Hello, world!" }
All three input tools auto-target the running playtest client ("client-1") when a playtest is active. If you are running a multiplayer test with multiple clients, pass target="client-2" (or the appropriate peer) to direct input at a specific client window.

Build docs developers (and LLMs) love

Get started for freeTalk to us