Vision Roblox MCP

Vision is a local Roblox Studio automation workbench and MCP server. It combines four backends instead of forcing every operation through one fragile channel:

Backend	Owns
Vision Studio plugin	Durable scene edits, undo recordings, approvals, retries, snapshots, properties, tags, grouping, and selection
Roblox Studio native MCP	Deep inspection, script tools, Luau execution, asset generation, viewport capture, playtesting, and input simulation
Rojo 7	Source-controlled Luau files, live source sync, builds, and sourcemaps
Vision MCP	One Codex-facing tool and resource surface that routes across the other three

The API and browser UI bind to 127.0.0.1. Vision does not use Roblox browser cookies. Open Cloud keys stay in the ignored local .env file.

What It Can Do

• Inspect up to 2,500 instances per Studio snapshot, including common properties, attributes, tags, scripts, selection, service ownership, and spatial data.
• Queue named tasks with queued, leased, succeeded, failed, and cancelled states.
• Retry failed tasks without losing history and recover leases after a Studio interruption.
• Apply task groups as Studio undo recordings through ChangeHistoryService.
• Create, move, clone, rename, pivot, group, ungroup, tag, select, focus, edit, and delete instances.
• Edit open scripts safely through ScriptEditorService and apply exact source patches.
• Insert approved assets, publish supported local assets through Open Cloud, and retain an audit trail.
• Connect to Roblox's built-in Studio MCP and expose its discovered tools with Vision safety gates.
• Start, stop, build, scaffold, and inspect Rojo projects from the UI or MCP.
• Expose 13 Codex MCP tools, three resources, and a reusable build prompt over stdio.

Install

Requirements: Node.js 20+, pnpm, Roblox Studio, and Windows PowerShell.

pnpm install
powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1
pnpm dev

Open http://127.0.0.1:5173, restart Roblox Studio, open the Vision plugin, and press Sync Scripts.

To enable Roblox's native MCP backend in a current Studio build:

1. Open Studio Assistant.
2. Click ... and open Manage MCP Servers.
3. Enable Studio as MCP server.
4. Return to Vision and press Connect under Roblox native MCP.

The tracked .codex/config.toml configures both vision_roblox and Roblox's native roblox_studio server for Codex when the repository is trusted. Start the Vision API before asking Codex to use Vision tools.

Commands

pnpm dev          # UI on 5173 and API on 5174
pnpm test         # durable queue and lease regression suite
pnpm build        # type-check and production web build
pnpm mcp          # run the Codex-facing stdio MCP server
pnpm verify:mcp   # perform a real initialize/list handshake
pnpm start        # API only

Safety Model

Vision classifies operations as read, write, destructive, code, asset, or playtest. Destructive edits, script changes/Luau execution, asset insertion, and playtest automation have separate switches. Native MCP mutation calls also require an explicit approved flag. Live mode only bypasses proposal creation for capabilities already enabled by those switches.

Studio changes use undo recordings whenever the plugin applies a task group. Task leasing prevents a failed request or Studio restart from silently deleting queued work.

Documentation

• Architecture
• Codex and MCP integration
• Roblox and Rojo limits
• Open Cloud setup
• Studio plugin contract

Current Limits

• Roblox creates its native MCP launcher only after Studio as MCP server is enabled in Assistant. Restart Studio and Codex if a newly enabled server is not discovered.
• Studio plugins cannot write every protected or security-scoped property. Failed properties are reported against the task and remain retryable.
• Snapshot sync is capped at 2,500 scene objects. Native MCP inspection is the preferred path for larger places.
• Rojo owns files that are inside its project mapping. Use the Vision plugin for instances intentionally outside that mapping.
• Asset upload support follows Roblox Open Cloud's current supported types, permissions, size limits, moderation, and asynchronous operation behavior.

License

MIT