roblox-studio-mcp

Roblox Studio MCP: remote-controlling Studio

The Studio MCP lets you run code inside a live Studio, inspect/modify the datamodel, screenshot, and generate content. This is the toolbox reference; for the disk→Rojo→test dev LOOP see the roblox-studio-workflow skill.

Connecting (and fixing a dead link)

• Studio dials OUT to the MCP hub and registers its tools. If Studio never connects, the MCP answers with 0 tools — ToolSearch/mcp__Roblox_Studio__* find nothing.
• Enable it in Studio: Assistant panel → Assistant Settings → "Enable Studio as MCP server". A green indicator under "Manage MCP Servers" = connected. Docs: create.roblox.com/docs/studio/mcp
• Dead-link fixes (in order): (1) toggle "Enable Studio as MCP server" off/on while a Codex session is running; (2) restart Studio after saving that setting; (3) an already-open Codex session may still hold the empty tool list — reconnect via /mcp or start a fresh session. A Studio that auto-updated & relaunched before the MCP existed is the classic "enabled but not connected" case.
• The MCP link can silently drop mid-session (the server disconnects) — after that the tools are gone until Studio reconnects. If tool calls start failing, check whether the link dropped before assuming a code problem.

Core tools (verified, used constantly)

• execute_luau — run Luau in Studio. Requires datamodel_type: Edit | Server | Client. Runs in a SEPARATE Lua VM: the DataModel is shared (Instances, PlayerGui, Workspace, Net remotes), but require() module state is NOT — you get a fresh copy, so you can't read/mutate a live module's singletons. FireAllClients only works from Server. Pure functions can be unit-tested with synthetic inputs here.
• start_stop_play — is_start bool (true=play, false=stop). Pair with the Rojo sync wait (see workflow skill) so you don't test stale code.
• get_console_output — read the output/errors. ALWAYS check after a boot for silent failures (e.g. "Out of local registers", a stuck WaitForChild, a service error).
• screen_capture — needs a capture_id. Artifacts to know: a freecam/scripted camera can leave ScreenGuis hidden, and distant SurfaceGui close-ups render blank — those are capture bugs, not game bugs (cross-check via instance queries). Coords for clicking are GUI AbsolutePosition space, not screenshot pixels — read AbsolutePosition + AbsoluteSize/2 first.
• user_mouse_input / user_keyboard_input — simulate input. Both also require datamodel_type (not obvious from the schema). user_mouse_input supports an instance_path form to click a GUI object without coords. Keyboard fails with "CoreGUI has keyboard focus" when a core UI (chat, menu) owns focus. Note: VirtualInputManager:SendMouseButtonEvent inside execute_luau FAILS ("lacking capability") — use these MCP input tools instead.
• inspect_instance / search_game_tree — inspect/find instances in the datamodel.
• script_read / script_grep / script_search — read/search the SCRIPTS currently in the datamodel. Great for confirming Rojo actually synced your latest edit: script_grep for a new comment string before you trust a playtest.

Content-generation & asset tools (mostly UNTRIED here — explore, verify behavior)

• generate_mesh — AI-generate a MeshPart from a prompt. generate_material — AI material/SurfaceAppearance. generate_procedural_model — a whole procedural model. Likely async → pair with wait_job_finished. Great for props/terrain/first-pass models; not yet exercised — validate quality + how the result lands in the datamodel.
• insert_asset (takes an assetId) — insert a Creator-Store asset. search_asset — searches the Creator Store only (Models/Images/Decals/etc.), NOT the avatar Marketplace (clothing/hair need the catalog Web API — see roblox-avatar-appearance).
• upload_image / store_image — upload local PNGs → rbxassetid://. upload_image takes imagePaths and needs http/https URLs (local paths fail): serve a folder over localhost (python3 -m http.server 8777), pass http://localhost:8777/foo.png, get back the id; kill the server (pkill -f "http.server 8777") when done. Byte-identical images dedup to the SAME id (re-uploading is safe). Batches fine (many at once). http_get — fetch a URL from Studio.
• character_navigation — move/navigate the player character (untried; useful for walking to a spot before a screenshot or proximity interaction).
• get_studio_state / list_roblox_studios / set_active_studio — multi-Studio awareness; point the tools at a specific open Studio when more than one is running.
• multi_edit — edits scripts IN the datamodel. Avoid for disk-authored (Rojo) scripts — it causes drift/duplicate instances (author those on disk; see roblox-studio-workflow). Reserve for scripts that live only in the datamodel.

Golden rules

• datamodel_type is required on execute_luau and the input tools — pick Server for server APIs (DataStore, MessagingService, FireAllClients, LoadAsset), Client for PlayerGui/local checks, Edit for pre-play datamodel/property changes.
• Set place properties / geometry in Edit mode so they persist (they need a place SAVE to be permanent); code belongs on disk via Rojo, not the MCP.
• Verify via observable side-effects on Instances, never a live module's internal fields (cross-VM). See the testing strategy in roblox-studio-workflow.
• If tools vanish mid-task, suspect a dropped link (above) before a code bug.