{
  "markdown": "# Roblox Studio MCP Bridge\n\nA [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that connects AI coding assistants like **Claude Code** directly to **Roblox Studio**. Read, create, modify, and delete instances in the DataModel — all from your terminal.\n\n## How It Works\n\n```\nClaude Code (MCP Client)\n        |\n   MCP Server (stdio)\n        |\n   HTTP Bridge (localhost:3001)\n        |\n   Studio Plugin (polls every 200ms)\n        |\n   Roblox Studio DataModel\n```\n\nThe bridge has two halves:\n\n1. **MCP Server** (TypeScript) — Runs locally, exposes 14 tools via MCP over stdio, and serves an HTTP API on `localhost:3001`\n2. **Studio Plugin** (Luau) — Polls the HTTP API for commands, executes them against the DataModel, and returns results\n\nAll write operations are wrapped in `ChangeHistoryService`, so every change can be undone with `Ctrl+Z` in Studio.\n\n## Available Tools\n\n| Tool | Type | Description |\n|------|------|-------------|\n| `get_descendants` | Read | Get all descendants with paths, optional `maxDepth` |\n| `get_children` | Read | Get immediate children of an instance |\n| `get_properties` | Read | Get serialized properties of an instance |\n| `find_instances` | Read | Search by `className` and/or `namePattern` |\n| `get_services` | Read | List all DataModel services |\n| `get_selection` | Read | Get currently selected instances in Studio |\n| `create_instance` | Write | Create a new Instance with properties |\n| `set_properties` | Write | Modify properties on an existing instance |\n| `delete_instance` | Write | Destroy an instance (undo-supported) |\n| `clone_instance` | Write | Clone an instance to a new parent |\n| `move_instance` | Write | Reparent an instance |\n| `set_selection` | Write | Set the Studio selection |\n| `insert_service` | Write | Insert a service via `game:GetService()` |\n| `execute_luau` | Write | Execute arbitrary Luau code in the plugin context |\n\nPaths use dot-notation starting from `game`, e.g. `game.Workspace.SpawnLocation`.\n\n## Prerequisites\n\n- **Node.js** 18+\n- **Roblox Studio**\n- **Rojo** 7+ ([aftman](https://github.com/LPGhatguy/aftman) or standalone install)\n\n## Installation\n\n### 1. Clone the repository\n\n```bash\ngit clone https://github.com/Justice219/roblox-studio-mcp.git\ncd roblox-studio-mcp\n```\n\n### 2. Install dependencies and build\n\n```bash\nnpm install\nnpm run build\n```\n\nOr install directly from npm:\n\n```bash\nnpm install -g @jamesworkbenchcrm/roblox-studio-mcp\n```\n\n### 3. Build and install the Studio plugin\n\nUsing Rojo:\n\n```bash\nrojo build plugin.project.json -o MCPBridge.rbxmx\n```\n\nThen copy the plugin file to your Roblox plugins folder:\n\n| OS | Path |\n|----|------|\n| macOS | `~/Documents/Roblox/Plugins/MCPBridge.rbxmx` |\n| Windows | `%LOCALAPPDATA%\\Roblox\\Plugins\\MCPBridge.rbxmx` |\n\nOr build directly to the plugins folder:\n\n```bash\n# macOS\nrojo build plugin.project.json -o ~/Documents/Roblox/Plugins/MCPBridge.rbxmx\n\n# Windows\nrojo build plugin.project.json -o \"%LOCALAPPDATA%\\Roblox\\Plugins\\MCPBridge.rbxmx\"\n```\n\n### 4. Enable HttpService in Studio\n\nOpen Roblox Studio, then:\n\n**Home → Game Settings → Security → Allow HTTP Requests → ON**\n\nThis is required for the plugin to communicate with the local MCP server.\n\n### 5. Configure your MCP client\n\nAdd the server to your MCP client configuration.\n\n**Claude Code** (`~/.claude/settings.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"roblox-studio\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/roblox-studio-mcp/dist/index.js\"]\n    }\n  }\n}\n```\n\n**Claude Desktop** (`claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"roblox-studio\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/roblox-studio-mcp/dist/index.js\"]\n    }\n  }\n}\n```\n\nReplace `/absolute/path/to/` with the actual path where you cloned the repo.\n\n### 6. Restart Studio and your MCP client\n\n- Restart Roblox Studio (or reload plugins) — you should see an \"MCP Bridge\" button in the toolbar\n- Restart Claude Code / your MCP client\n- The plugin status widget will show a green dot when connected\n\n## Usage\n\nOnce connected, your AI assistant can manipulate Studio directly:\n\n```\n\"Create a Part named SpawnPad in Workspace at position 0, 5, 0\"\n\"Get all children of ServerScriptService\"\n\"Find all instances with className RemoteEvent\"\n\"Set the BrickColor of game.Workspace.SpawnPad to Bright green\"\n```\n\nThe assistant uses the MCP tools to read the DataModel, create instances, set properties, and more — all reflected live in Studio with full undo support.\n\n## Configuration\n\n| Environment Variable | Default | Description |\n|---------------------|---------|-------------|\n| `MCP_BRIDGE_PORT` | `3001` | HTTP bridge port |\n\n```bash\nMCP_BRIDGE_PORT=4000 npm start\n```\n\n## Development\n\n```bash\n# Watch mode — recompiles on file changes\nnpm run dev\n\n# Type-check without emitting\nnpm run typecheck\n\n# Build\nnpm run build\n\n# Start the server\nnpm start\n```\n\n## Architecture\n\n```\nsrc/\n├── index.ts           # Entry point — wires up all components\n├── types.ts           # Interfaces, constants, command type definitions\n├── mcp-server.ts      # MCP tool definitions (14 tools with Zod validation)\n├── http-bridge.ts     # Express HTTP server (poll/result/heartbeat endpoints)\n└── command-queue.ts   # In-memory command queue with timeout management\n\nplugin/\n├── init.server.luau   # Plugin entry point — polling loop, UI, toolbar\n└── modules/\n    ├── CommandRouter.luau  # Dispatches commands to handlers\n    ├── HttpClient.luau     # HTTP requests to the bridge\n    ├── PathResolver.luau   # Dot-notation path ↔ Instance resolution\n    └── Serializer.luau     # Roblox type ↔ JSON serialization\n```\n\n## Security\n\n- The HTTP bridge **only binds to `127.0.0.1`** — it is never exposed to the network\n- Write operations are wrapped in `ChangeHistoryService` for undo support\n- Commands timeout after 30 seconds\n- Connection requires heartbeat every 10 seconds\n- `execute_luau` runs code in the plugin context with no sandboxing — only use with trusted input\n\n## Supported Roblox Types\n\nThe serializer handles bidirectional conversion for:\n\n`Vector3` · `Vector2` · `CFrame` · `Color3` · `BrickColor` · `UDim` · `UDim2` · `Rect` · `NumberSequence` · `ColorSequence` · `NumberRange` · `Enum` · `Instance` · `Font` · `PhysicalProperties` · `Ray`\n\nAll types use a `{ _type: \"TypeName\", ... }` JSON format for lossless round-tripping.\n\n## Troubleshooting\n\n**Plugin shows red dot / \"Disconnected\"**\n- Make sure the MCP server is running (`npm start`)\n- Check that HttpService is enabled in Studio\n- Verify the port matches (default `3001`)\n\n**\"Plugin not connected\" error in Claude Code**\n- Open Studio and check the MCP Bridge toolbar button is enabled\n- The plugin auto-starts on load — try reloading plugins\n- Check Studio's Output window for error messages\n\n**Port already in use**\n- Another instance may be running. Kill it or use a different port:\n  ```bash\n  MCP_BRIDGE_PORT=4000 npm start\n  ```\n\n## npm\n\n```bash\nnpm install -g @jamesworkbenchcrm/roblox-studio-mcp\n```\n\nhttps://www.npmjs.com/package/@jamesworkbenchcrm/roblox-studio-mcp\n\n## License\n\nMIT\n",
  "bytes": 7092,
  "sha": "7fdfffe27d05ed392f16263a3804ff6dfe4144200bbde2349203e378e0972230",
  "repo_slug": "justice219/roblox-studio-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_justice219_roblox_studio_mcp_ddbd9104/readme"
}