roblox-mcp — Claude Code skill for Roblox Studio via MCP

---
name: roblox-mcp
description: "Connect an AI client to Roblox Studio through MCP. Use for connection setup, Studio tools, multiple Studio windows, playtesting, or combining MCP with Script Sync."
last_reviewed: 2026-06-17
---

# roblox-mcp

**Official sources:**
- 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

The official Roblox Studio MCP server lets a connected AI client inspect and edit an open place. It provides tools for scripts, instances, Luau execution, assets, and playtesting.

## 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](https://create.roblox.com/docs/studio/setup).
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** 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.

For clients that read an `mcp.json` or similar config file, see [references/setup-and-connection.md](references/setup-and-connection.md) for per-OS, copy-paste configurations.

For clients that need a raw CLI command, see [references/setup-and-connection.md](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 current tool names and usage guidance are in [references/tool-reference.md](references/tool-reference.md).

| Category | Examples |
| --- | --- |
| **Scripts** | `script_read`, `multi_edit`, `script_search`, `script_grep` |
| **Data model** | `search_game_tree`, `inspect_instance`, `subagent` (`explore`) |
| **Luau execution** | `execute_luau` |
| **Asset generation & insertion** | `generate_mesh`, `generate_material`, `generate_procedural_model`, `wait_job_finished`, `search_asset`, `insert_asset`, `upload_image`, `store_image` |
| **Playtesting** | `start_stop_play`, `get_studio_state`, `get_console_output`, `screen_capture`, `subagent` (`playtest`) |
| **Input simulation** | `character_navigation`, `user_keyboard_input`, `user_mouse_input` |
| **Documentation** | `http_get`, `skill` |
| **Instance discovery** | `list_roblox_studios`; pass `studio_id` on subsequent calls |

## Work with MCP and Script Sync

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](references/script-sync-integration.md) for the full setup and a starter-project layout.

## Multi-instance handling

Call `list_roblox_studios` to discover connected windows, their Studio instance IDs, and place IDs. Local places without a place ID are listed by name. Pass the selected instance's `studio_id` on every subsequent tool call; do not rely on a shared active window or infer the target from an object path. Re-list instances when a window closes or the target changes.

## 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](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](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](references/script-sync-integration.md).
5. Use the tool reference to craft precise agent prompts and the security guide to keep the workflow safe.

<!-- catalog:references:start -->
## Reference index

- [script-sync-integration.md](references/script-sync-integration.md): Combine files on disk with Studio MCP edits and playtests.
- [security-and-troubleshooting.md](references/security-and-troubleshooting.md): Investigate MCP connection failures or review Studio access.
- [setup-and-connection.md](references/setup-and-connection.md): Enable Studio MCP and connect a client on Windows or macOS.
- [tool-reference.md](references/tool-reference.md): Choose a Studio MCP tool and identify the target Studio instance.
<!-- catalog:references:end -->