Roblox Mcp

roblox-mcp

Official sources (always check these for the latest):

• https://create.roblox.com/docs/en-us/studio/mcp
• https://create.roblox.com/docs/en-us/ai/build
• https://create.roblox.com/docs/en-us/scripting/sync
• https://modelcontextprotocol.io/docs/getting-started/intro

This skill is about the official Roblox Studio MCP server, not a third-party wrapper. Once connected, your AI client can drive an open Roblox Studio session: read and edit scripts, search the game tree, run Luau, insert assets, start playtests, simulate input, and capture the viewport.

When to use this skill

Activate when the user is:

• Setting up an AI coding tool (Cursor, VS Code + Claude Code, Claude Desktop, Codex CLI, etc.) to talk to Roblox Studio.
• Asking about the Roblox Studio MCP server, MCP tools, or the coding-harness workflow.
• Combining Script Sync with agent-driven Studio control.
• Troubleshooting why MCP tools are not showing up or not executing.
• Writing prompts or workflows that let an agent safely modify a place.

Cross-reference:

• roblox/SKILL.md for general Roblox architecture and specialized development skills.
• roblox-core/SKILL.md for services, script locations, and the data model.

What the Studio MCP server is

Roblox Studio implements a Model Context Protocol (MCP) server using stdio transport. The server runs as a local process on your machine and proxies requests from a supported AI client into the active Studio session. It is the bridge between your editor's agent and Studio: Script Sync handles disk-to-Studio file syncing, while MCP handles everything else (Explorer selection, instance inspection, script editing, Luau execution, play mode, input simulation, and asset insertion).

Prerequisites

1. Latest Roblox Studio — update through the launcher or download from the Creator Hub. 2. An MCP-capable AI client — Cursor, VS Code with Claude Code, Claude Desktop, Codex CLI, Gemini CLI, Antigravity, or any client that supports stdio transport. 3. A Roblox account signed into Studio. 4. Git (recommended) for the file-based workflow.

Enabling the server in Studio

1. Open Studio and load the place you want the agent to work on. 2. Open Assistant (button in the upper right). 3. Click ⋯ → Manage MCP Servers. 4. Turn on Enable Studio as MCP server. 5. The panel shows quick-connect options and manual configuration snippets. A green indicator appears when a client connects.

If you do not see MCP options, restart Studio after updating to the latest version.

Connecting your client

Choose the method that matches your client:

Quick connect — easiest. Supports Antigravity, Codex CLI, Claude Code, Claude Desktop, Cursor, Gemini CLI, and Visual Studio Code. 1. In Studio: Assistant → ⋯ → Manage MCP Servers → Quick connect. 2. Turn on your installed client. 3. Restart the client if the tools do not appear immediately.

JSON configuration — for clients that read an mcp.json or similar config file. See references/setup-and-connection.md for per-OS, copy-paste configurations.

CLI command — for clients that need a raw command. See references/setup-and-connection.md for Windows and macOS commands.

After connecting, verify with:

Use the Roblox MCP to read the current game tree in Roblox Studio. List what's in Workspace.

What you can do with the MCP tools

The server exposes tools in several categories. The full list, parameters, and example prompts are in references/tool-reference.md.

MCP + Script Sync: the complete agent workflow

Script Sync maps folders on disk (ServerScriptService/, ReplicatedStorage/, StarterPlayerScripts/, etc.) to Studio services, so .luau files you edit locally appear in Studio automatically. MCP covers everything Script Sync cannot reach: editing StarterGui, inserting models, running commands, playtesting, and inspecting instances.

Typical agent loop: 1. Edit disk files through Script Sync for reusable modules and scripts. 2. Use MCP to inspect instances, run Luau snippets, start play mode, and capture output/screenshots. 3. Use MCP to edit scripts that live in containers not covered by Script Sync (for example, StarterGui).

See references/script-sync-integration.md for the full setup and a starter-project layout.

Multi-instance handling

You can connect one MCP client to multiple Studio windows. The server usually picks the right instance from context (for example, an object path that only exists in one place). To switch manually, use:

• list_roblox_studios — show all connected Studio instances.
• set_active_studio — target a specific instance for subsequent calls.

Security and trust

MCP clients can read and modify your open places. Treat MCP connections like any privileged integration:

• Only connect clients you trust.
• Work on test places or version-controlled projects.
• Review agent edits before publishing.
• Keep .rbxlx and other place files out of Git (use the starter .gitignore).
• Disconnect or disable the MCP server when it is not in use.
• Treat execute_luau as privileged code: it can publish places, write to DataStores, make HTTP requests, and access credentials loaded in Studio.

See references/security-and-troubleshooting.md for the full security checklist and troubleshooting steps.

Verification checklist

• [ ] Studio is updated and MCP is enabled.
• [ ] AI client shows the Roblox MCP tools after restart.
• [ ] script_read or search_game_tree returns the current place structure.
• [ ] Script Sync maps the expected service folders to disk (if using file-based workflow).
• [ ] execute_luau can run a simple print and return output.
• [ ] start_stop_play enters/exits play mode successfully.

Scripts

• scripts/MCPReadyChecker.lua — a diagnostic snippet you can run with execute_luau to verify Script Sync status and basic model health.
• scripts/StudioModelProbe.lua — a reusable utility for summarizing the game tree, useful as a pattern for agent exploration prompts.

How to proceed

1. Confirm prerequisites and enable MCP in Studio. 2. Connect your client using quick connect or the manual config in references/setup-and-connection.md. 3. Verify the connection with a simple tree-read or execute_luau call. 4. If using a file-based workflow, set up Script Sync per references/script-sync-integration.md. 5. Use the tool reference to craft precise agent prompts and the security guide to keep the workflow safe.

Script Sync Integration

Official guides:

• https://create.roblox.com/docs/en-us/scripting/sync
• https://create.roblox.com/docs/en-us/ai/build

What Script Sync does

Script Sync lets you edit Luau scripts on your local disk with any text editor or AI agent, then syncs those files into Roblox Studio automatically. It covers disk-to-Studio mapping for services such as:

• ServerScriptService/
• ReplicatedStorage/
• StarterPlayerScripts/
• Other eligible service folders

Files you create or edit in those mapped folders appear as scripts in the Explorer almost immediately.

Enable Script Sync

Script Sync is a beta feature.

1. In Studio: File → Beta Features. 2. Find Script Sync, enable it, and save. 3. Restart Studio when prompted.

Connect each service to a disk folder

1. In the Explorer, right-click a service (for example, ServerScriptService). 2. Choose Script Sync → Sync with Directory. (Older Studio builds labeled this Sync to.) 3. Browse to your project folder.

Important:

• Select the top-level project folder, not the individual service folders inside it.
• If your folders are named exactly ServerScriptService, ReplicatedStorage, and StarterPlayerScripts, Script Sync matches them automatically.

File naming conventions

Script Sync uses the file extension to decide which Roblox script class to create. Use the exact suffixes below:

Common mistakes:

• Test.shared.luau does not create a ModuleScript named Test. It creates an instance literally named Test.shared. Use Test.luau for a ModuleScript.
• Test.client.luau creates a Script with RunContext = Client, not a LocalScript. Use Test.local.luau for a LocalScript.

Typical project layout

The official starter project (WaveSurvival.zip) uses this structure:

WaveSurvival/
├── .gitignore
├── WaveSurvival.rbxlx          # excluded from Git by .gitignore
├── ServerScriptService/        # server logic
├── ReplicatedStorage/          # shared modules
└── StarterPlayerScripts/       # client scripts

Use .gitkeep files to preserve empty folders in Git until you add real scripts.

Where MCP fits in

Script Sync handles scripts that map to disk. MCP handles everything else:

End-to-end verification prompt

After both Script Sync and MCP are connected, ask your agent:

Use the Roblox MCP connection to verify Script Sync is working properly. Create ServerScriptService/Test.server.luau, ReplicatedStorage/Test.luau, and StarterPlayerScripts/Test.local.luau that each print a distinct message, then run game:GetService("InstanceFileSyncService"):GetStatus(instance) on each to confirm sync status. Start play mode, capture the output, and then delete the test scripts.

This confirms:

• MCP can create and edit scripts.
• Script Sync maps the expected folders.
• execute_luau and console_output work.
• Play mode starts and stops cleanly.

Script Sync warnings and limitations

• Attributes and tags are ignored. Script Sync does not preserve Instance:SetAttribute() values or CollectionService tags. Back up your place before syncing, or store that data outside synced scripts.
• Back up your place first. Syncing can overwrite or delete instances if file names change or files are removed.
• Both Script Sync and the Studio MCP server are beta features. Behavior and menu names may change.
• Editing a synced script through MCP can cause conflicts. If Script Sync is active for a service, prefer editing the source file on disk. MCP edits may be overwritten on the next sync.
• Use caution with Team Create. Multiple authors, or an agent plus Script Sync, can overwrite each other's changes.
• Use the Luau LSP (for example, the JohnnyMorganz.luau-lsp VS Code extension) for diagnostics, autocomplete, and type-checking in the synced files.

Best practices

• Keep place files (.rbxl, .rbxlx) out of Git; commit only source scripts and config.
• Use Script Sync for long-lived code; use MCP for ad-hoc Studio operations.
• When an agent edits a script via MCP, verify the change in the Explorer or with script_read.
• Run playtests frequently when iterating with an agent.

Security and Troubleshooting

Security checklist

MCP clients have broad access to your open Studio session. Follow these rules:

• [ ] Only connect MCP clients you trust.
• [ ] Use test places or copies of live places for agent experimentation.
• [ ] Keep your project under version control so you can review and revert agent changes.
• [ ] Do not commit place files (.rbxl, .rbxlx) or credentials to Git.
• [ ] Avoid running untrusted execute_luau snippets. Executed code can publish places, write to DataStores, make HTTP requests, access plugin-level APIs, read credentials loaded in Studio, and exfiltrate data. Run only in test places and review every snippet.
• [ ] Review generated mesh/material/procedural model insertions before publishing.
• [ ] When working in a team, coordinate so only one agent session targets a given Studio instance at a time.

Trust model

The MCP server runs locally and communicates over stdio. Studio initiates the server; your AI client connects to it. While no credentials flow through the AI client directly, executed Luau runs with your signed-in Studio privileges and can access credentials stored in Studio, make network requests, and call Roblox web APIs.

Disconnecting or disabling the server when not in use

• In Studio: Assistant → ⋯ → Manage MCP Servers and turn off Enable Studio as MCP server.
• Disconnect or remove the Roblox_Studio entry from your MCP client's configuration.
• Close Studio windows you are not using.

This reduces the chance of accidental or unintended agent actions.

Common issues and fixes

MCP tools do not appear in the AI client

1. Restart the AI client completely (not just the chat panel). 2. Restart Roblox Studio. 3. Confirm Enable Studio as MCP server is turned on. 4. Check the config file path or quick-connect setting. 5. If using JSON config, validate JSON syntax (missing commas are the most common cause).

Quick connect does not list my client

• Install or update the client, then restart Studio.
• Some clients require a full machine restart of the client process to register.

execute_luau returns an error

• The code runs inside Studio, so it must be valid Luau in the current context.
• Remember the client/server boundary: code runs in Studio's edit context unless play mode is active.
• Check that instances referenced in the code exist.

Script Sync changes are not showing up

• Verify the service is synced to the correct top-level folder.
• Ensure file names end in .luau.
• Check that the beta feature is enabled and Studio was restarted.
• Use game:GetService("InstanceFileSyncService"):GetStatus(instance) on the script to inspect sync state.

Play mode capture or input simulation fails

• Start play mode first with start_stop_play.
• Wait a moment for the play session to initialize before capturing or sending input.
• Some tools require the viewport to be in a valid state.

Multiple Studio instances are confusing the agent

• Use list_roblox_studios to see all open instances.
• Use set_active_studio to lock the target instance.
• Close unused Studio windows when possible.

JSON syntax quick check

A valid mcpServers block has entries separated by commas:

{
  "mcpServers": {
    "Roblox_Studio": {
      "command": "cmd.exe",
      "args": ["/c", "%LOCALAPPDATA%\\Roblox\\mcp.bat"]
    },
    "Another_Server": {
      "command": "..."
    }
  }
}

Use an online JSON validator or your editor's JSON diagnostics if the config does not load.

Getting more help

• Official MCP connection guide: https://create.roblox.com/docs/en-us/studio/mcp
• Coding harness tutorial: https://create.roblox.com/docs/en-us/ai/build
• Script Sync docs: https://create.roblox.com/docs/en-us/scripting/sync
• MCP protocol overview: https://modelcontextprotocol.io/docs/getting-started/intro

Setup and Connection

Official guide: https://create.roblox.com/docs/en-us/studio/mcp

Quick connect

The fastest path. Studio detects supported clients installed on your machine.

Supported clients (as of the latest docs):

• Antigravity
• Codex CLI
• Claude Code
• Claude Desktop
• Cursor
• Gemini CLI
• Visual Studio Code

Steps: 1. In Studio: Assistant → ⋯ → Manage MCP Servers. 2. Make sure Enable Studio as MCP server is on. 3. Expand Quick connect. 4. Turn on the client you want to use. 5. Restart the AI client if its tool list does not update immediately.

If your client does not appear, install it and restart Studio.

JSON configuration

Most MCP clients read a JSON config file. Add the Roblox_Studio entry under mcpServers.

Windows

{
  "mcpServers": {
    "Roblox_Studio": {
      "command": "cmd.exe",
      "args": [
        "/c",
        "%LOCALAPPDATA%\\Roblox\\mcp.bat"
      ]
    }
  }
}

macOS

{
  "mcpServers": {
    "Roblox_Studio": {
      "command": "/Applications/RobloxStudio.app/Contents/MacOS/StudioMCP"
    }
  }
}

Notes:

• If you already have other servers, add a comma after the previous entry and paste the Roblox_Studio block.
• Validate JSON syntax. A missing comma or bracket prevents the config from loading.
• Paths assume the default install location. Adjust if you installed Studio elsewhere.

CLI command

Some clients accept a raw command instead of JSON.

Windows

cmd.exe /c %LOCALAPPDATA%\Roblox\mcp.bat

macOS

/Applications/RobloxStudio.app/Contents/MacOS/StudioMCP

Client-specific hints

Cursor

• Open Cursor Settings → MCP, or use the project's .cursor/mcp.json file.
• Paste the JSON config or use quick connect if Cursor is detected by Studio.

Visual Studio Code + Claude Code

• Use VS Code's settings or the workspace's .vscode/mcp.json for the server config.
• Install the Claude Code extension, sign in, and open the chat panel.

Claude Desktop

• Edit claude_desktop_config.json (location varies by OS) and add the Roblox_Studio entry.

Codex CLI / Gemini CLI / Antigravity

• Follow the tool's own MCP config convention; the command/args values above are what matter.

Verify the connection

1. In Studio, open Assistant → ⋯ → Manage MCP Servers. 2. Look for the green indicator under Enable Studio as MCP server showing connected clients. 3. In your AI client, run:

Use the Roblox MCP to list what's in game.Workspace.

You may need to approve the first request or add the tool to an allowlist, depending on the client.

If no tools appear:

• Restart both Studio and the AI client.
• Check that the command path exists on disk.
• Validate your JSON config.

MCP Tool Reference

Official source: https://create.roblox.com/docs/en-us/studio/mcp

This file describes each tool the Roblox Studio MCP server exposes, plus practical prompt patterns. All actions target the currently active Studio instance (use list_roblox_studios + set_active_studio to switch).

Scripts

script_read

Reads a script from the game using dot-notation paths such as game.ServerScriptService.MyScript.

Good for: quickly viewing source without leaving your editor.

Example prompt:

Use script_read to show me the full contents of game.ServerScriptService.GameLogic.

To read a specific range:

Use script_read on game.ReplicatedStorage.Config and return lines 10 through 30.

multi_edit

Applies multiple edits to a script in one call. If the target path does not exist, it creates a new script.

Good for: batch refactors, adding imports, or creating new scripts from a template.

Example prompt:

Use multi_edit on game.ServerScriptService.MyModule to replace print("old") with print("new") and add local RunService = game:GetService("RunService") at the top.

script_search

Fuzzy search for scripts by name. Returns up to 10 results.

Good for: finding a script when you only remember part of its name.

Example prompt:

Use script_search to find any script named something like "Inventory".

script_grep

Searches for a string pattern across all scripts in the game. Returns up to 50 matches.

Good for: finding every usage of a function or deprecated API.

Example prompt:

Use script_grep to find every occurrence of Humanoid:LoadAnimation.

Data model exploration

explore_subagent

Spawns a parallel investigation of your place and returns a compact summary. Keeps the main conversation clean.

Good for: large places where a full tree dump would be overwhelming.

Example prompt:

Use explore_subagent to summarize the Workspace structure and highlight any scripts that look like they handle player input.

search_game_tree

Explores the instance hierarchy as a flat JSON array. Supports filtering by path, instance type, and keywords.

Good for: targeted exploration — for example, "every Part under Workspace" or "every ModuleScript under ReplicatedStorage".

Example prompt:

Use search_game_tree to list all Part instances under game.Workspace.

inspect_instance

Returns detailed information about a specific instance: readable properties, custom attributes, and a summary of children/descendants.

Good for: debugging why something behaves a certain way or checking attributes.

Example prompt:

Use inspect_instance on game.Workspace.SpawnLocation and tell me its properties and attributes.

Luau execution

execute_luau

Runs arbitrary Luau code inside Studio. Returns the result or an error.

Good for: quick tests, one-off fixes, inspecting runtime state, or triggering actions that do not have a dedicated tool.

Example prompt:

Use execute_luau to run print(game:GetService("Players").NumPlayers) and show me the output.

Security warning: execute_luau runs arbitrary Luau inside your signed-in Studio session. It can publish places, write to DataStores, make HTTP requests, access plugin-level APIs, read credentials loaded in Studio, and exfiltrate data. Only run code you have reviewed. Use a test place, and enable per-tool allowlists in your MCP client if available.

Asset and content generation

generate_mesh

Generates a textured 3D mesh.

Example prompt:

Use generate_mesh to create a low-poly rock mesh and insert it under game.Workspace.

generate_material

Generates a custom material or texture.

Example prompt:

Use generate_material to generate a worn metal material and apply it to game.Workspace.Platform.

generate_procedural_model

Generates procedural models that scale and adapt automatically.

Example prompt:

Use generate_procedural_model to generate a small procedural tree and place it at game.Workspace.TreeSpawn.

insert_from_creator_store

Inserts assets, plugins, and models from the Creator Store.

Example prompt:

Use insert_from_creator_store to insert asset ID 123456789 as a model under game.Workspace.

Playtesting

start_stop_play

Starts or stops playtesting.

Example prompt:

Use start_stop_play to start playtesting.

console_output

Retrieves output logs while the game is running.

Example prompt:

Use console_output to fetch the last 50 lines of output from the running playtest.

screen_capture

Captures the current Studio viewport in Play mode and returns image data.

Example prompt:

Use screen_capture to take a screenshot of the current playtest view.

playtest_subagent

Spawns a test character that runs through gameplay scenarios.

Example prompt:

Use playtest_subagent to spawn a character and walk to game.Workspace.Goal.

Player input simulation

character_navigation

Moves the player character to a position or instance.

Example prompt:

Use character_navigation to move the player to the position (0, 10, 0).

keyboard_input

Simulates key presses, holds, and text input.

Example prompt:

Use keyboard_input to press the Space key once.

mouse_input

Simulates mouse clicks, movement, and scrolling.

Example prompt:

Use mouse_input to click at the center of the screen.

Session management

list_roblox_studios

Lists all connected Studio instances with name, ID, and active status.

Example prompt:

Use list_roblox_studios to show me all open Studio windows.

set_active_studio

Sets the target Studio instance for subsequent tool calls.

Example prompt:

Use set_active_studio to target the instance named "WaveSurvival".

Prompt-writing tips

• Be specific about instance paths (game.ServerScriptService.MyScript rather than "the server script").
• Prefer multi_edit for batch changes instead of many single edits.
• Use explore_subagent or search_game_tree before asking the agent to make broad changes.
• Combine execute_luau with console_output for quick test-driven checks.
• When playtesting, tell the agent to start play mode before capturing or simulating input.