Content
# Roblox Studio MCP
> **Experimental.** This is an active work-in-progress. APIs will change, features may break, and the rendered screenshots are blocky approximations — not pixel-accurate previews. Use at your own risk. Contributions and bug reports welcome.
An MCP (Model Context Protocol) server for controlling Roblox Studio from AI coding tools like [OpenCode](https://opencode.ai). Provides workspace exploration, instance manipulation, script management, toolbox integration, playtest controls, and viewport rendering.
## Architecture
```
OpenCode / Claude ──stdio/MCP──> MCP Server (Node.js) ──HTTP──> Studio Plugin (Lua)
:28821 bridge polls for commands
```
The MCP server runs a small HTTP server on `127.0.0.1:28821`. The Roblox Studio plugin polls this server every 250ms for pending commands, executes them inside Studio, and posts results back.
## Setup
### 1. Install dependencies and build
```bash
npm install
npm run build
```
### 2. Install the Studio plugin
**Automatic:**
```bash
npm run install-plugin
```
**Manual:**
Copy `plugin/RobloxStudioMCP.server.lua` to your Roblox Studio plugins folder:
| Platform | Path |
| -------- | -------------------------------- |
| macOS | `~/Documents/Roblox/Plugins/` |
| Windows | `%LOCALAPPDATA%\Roblox\Plugins\` |
### 3. Activate the plugin
In Studio, click the **MCP Bridge** button in the toolbar. A status widget will appear showing connection state.
> **Note:** Plugin HTTP requests are not gated by the "Allow HTTP Requests" game setting. That setting only applies to game scripts — plugins can make HTTP calls freely.
### 4. Configure OpenCode
The included `opencode.json` works when you run OpenCode from the project root:
```json
{
"mcp": {
"roblox-studio": {
"type": "local",
"command": ["node", "dist/index.js"],
"environment": {
"ROBLOX_MCP_PORT": "28821"
}
}
},
"default_agent": "studio"
}
```
If you want to use this from a different project, use the absolute path to `dist/index.js` in the command array.
## Tools (6 consolidated)
All tools use an `action` parameter to select the specific operation.
### `roblox_get` — Read-only queries
| Action | Description |
| --- | --- |
| `ping` | Check plugin connection status and get place info |
| `tree` | ASCII tree view of the instance hierarchy |
| `search` | Search by name substring and/or class name |
| `instance` | Get detailed info about a specific instance |
| `properties` | Read all common properties of an instance |
| `descendants_summary` | Class breakdown with counts for descendants |
| `selection` | Get currently selected instances |
| `output_log` | Read recent Output window entries |
| `texture_info` | Get texture/decal asset IDs for an instance and descendants |
### `roblox_manage` — Instance mutations
| Action | Description |
| --- | --- |
| `create` | Create Part, Model, Folder, etc. with properties |
| `create_multiple` | Batch create multiple instances at once |
| `update` | Update properties (Position, Size, Color, etc.) |
| `reset_pivot` | Reset a Model's WorldPivot to bounding box center |
| `delete` | Destroy an instance (undoable) |
| `clone` | Clone with optional rename/reparent |
| `reparent` | Move an instance to a new parent |
| `set_selection` | Select specific instances |
| `undo` | Undo last action |
| `redo` | Redo last undone action |
### `roblox_script` — Script CRUD & execution
| Action | Description |
| --- | --- |
| `create` | Create Script/LocalScript/ModuleScript |
| `read` | Read script source and metadata |
| `update` | Update source code (works with open editors) |
| `execute` | Execute a Lua snippet in Studio context |
### `roblox_scene` — Camera & screenshots
| Action | Description |
| --- | --- |
| `screenshot` | Render a PNG of the current viewport (geometry + color + materials, no textures) |
| `move_camera` | Position camera explicitly or auto-frame on an instance |
### `roblox_toolbox` — Creator Store
| Action | Description |
| --- | --- |
| `search` | Search for free models/decals/audio |
| `insert` | Insert a toolbox asset by ID |
| `strip_scripts` | Remove all scripts from an inserted model |
### `roblox_playtest` — Test sessions
| Action | Description |
| --- | --- |
| `start` | Begin a playtest session |
| `stop` | Stop the current playtest |
| `status` | Get current state (Edit/Run/Play) |
| `move_camera` | Move camera during playtest |
| `fire_click` | Fire a ClickDetector |
| `fire_proximity` | Trigger a ProximityPrompt |
| `get_state` | Read game state (players, leaderstats) |
| `execute` | Run Lua in the live game context |
## Instance Paths
Instances are referenced by dot-separated paths from `game`:
```
Workspace -- game.Workspace
Workspace.SpawnLocation -- a SpawnLocation in Workspace
ServerScriptService.GameScript -- a script in ServerScriptService
ReplicatedStorage.Modules.Utils -- nested path
```
## Agent
An OpenCode agent definition is included at `.opencode/agents/studio.md`. It configures the AI with Roblox Studio domain knowledge and tool usage patterns. The `opencode.json` sets it as the default agent.
## Environment Variables
| Variable | Default | Description |
| ----------------- | ------- | ---------------- |
| `ROBLOX_MCP_PORT` | `28821` | HTTP bridge port |
## Known Limitations
- **Screenshots** are software-rendered from geometry data — no textures, lighting, or post-processing. They show shapes, colors, and spatial relationships, not what Studio's viewport actually looks like.
- **Playtest control** uses `RunService:Run()`/`:Stop()` which works for server-side testing but doesn't fully replicate Play Solo (no local player character).
- **Toolbox search** hits the public Roblox API and may be rate-limited.
- **Script execution** runs via `require()` on a temporary ModuleScript. Some APIs may not be available in this context.
- **Instance paths** use dot-separated names, so instances with `.` in their name will not resolve correctly.
## License
MIT
