ZenMCPRoblox

<div align="center"> <img src="extension/assets/icon-256.png" width="180" alt="ZenMCPRoblox icon"> <h1>ZenMCPRoblox</h1> <p><strong>A secure local AI controller for Roblox Studio.</strong></p> <p>ChatGPT, DeepSeek, Gemini, Kimi, Z.ai/GLM, Qwen, Arena, or Meta AI → authenticated local bridge → MCP controller → Roblox Studio</p> </div>

[!IMPORTANT] ZenMCPRoblox is an independent community project. It is not affiliated with, endorsed by, or an official product of Roblox Corporation, OpenAI, Google, DeepSeek, Moonshot AI, Alibaba, Meta, LMSYS/Arena, Z.ai, Chrrxs, or ZeroScript.

What it does

ZenMCPRoblox connects supported AI chat websites to Roblox Studio without giving web pages unrestricted access to your computer. It combines a Chromium extension, an authenticated localhost bridge, a security-gated controller, and the current @chrrxs/robloxstudio-mcp backend.

The controller can dynamically discover the backend's current tools, inspect and edit places, route calls to multiple Studio instances, run playtests and debugging workflows, keep change history, invoke Studio undo, and retrieve official Roblox documentation for the AI.

Two frontend modes use the same browser-independent controller:

• Browser mode: AI website → ZenMCP extension → local bridge → controller.
• Native MCP mode: compatible MCP client → ZenMCP stdio server → controller.

Highlights

• Strict structured action protocol; ordinary AI prose is never executed.
• Localhost-only WebSocket bridge with token authentication.
• Safe Mode blocks writes; Edit Mode must be enabled explicitly.
• Dynamic discovery of upstream MCP commands and schemas.
• Multi-Studio discovery and instance_id routing.
• Change history and rollback through Roblox Studio undo.
• Debug, playtest, runtime-log, and asset-security workflows.
• Official Roblox API retrieval through upstream get_roblox_docs.
• Generated models are moved from mandatory upstream staging into Workspace.
• Automatic plugin installation/update where supported upstream.
• Reconnecting Manifest V3 extension with heartbeats and background recovery.
• Custom draggable and collapsible panel on supported AI websites.
• Native stdio MCP adapter for future browser-independent integrations.

Architecture

Browser mode

AI chat website
      │ strict <zenmcp-action> JSON
      ▼
ZenMCPRoblox Chromium extension
      │ authenticated WebSocket on localhost
      ▼
ZenMCP local bridge
      │ validated requests, permissions, history
      ▼
ZenMCP controller
      │ MCP over stdio
      ▼
@chrrxs/robloxstudio-mcp
      │ upstream Studio plugin transport
      ▼
Roblox Studio


Native mode

MCP client ──stdio──▶ ZenMCP controller ──MCP──▶ Roblox Studio backend

Results travel back through the same stack. The controller does not depend on an AI website's DOM; provider-specific browser code is isolated in the extension.

Supported browser providers

Provider	Website	Adapter status
ChatGPT	chatgpt.com	Supported
DeepSeek	chat.deepseek.com	Supported
Gemini	gemini.google.com	Supported
Kimi	kimi.com	Supported
Z.ai / GLM	chat.z.ai	Supported
Qwen	chat.qwen.ai	Supported
Arena	arena.ai	Supported; use a single/direct chat mode
Meta AI	meta.ai	Supported

AI websites can change their interfaces without notice. A site update may require its selector profile to be updated even though the controller and Roblox integration remain unaffected.

Requirements

• Node.js 20 or newer.
• npm and npx.
• Roblox Studio.
• Chrome, Chromium, or a compatible Manifest V3 browser.
• A Roblox place open in Studio.
• Allow HTTP Requests enabled in Studio under Game Settings → Security.

Installation

From the directory containing this project:

cd ZenMCPRoblox
npm install
npm run setup

Setup performs the following operations:

1. Checks Node.js, npm, and npx.
2. Installs or updates @chrrxs/robloxstudio-mcp@latest.
3. Generates .zenmcp/config.json with a random local bridge token.
4. Builds the TypeScript controller and browser extension.
5. Installs or updates the matching upstream Roblox Studio plugin.
6. Runs connection diagnostics.

Fully close and reopen Roblox Studio after the plugin is first installed or updated.

Load the browser extension

1. Open chrome://extensions.
2. Enable Developer mode.
3. Select Load unpacked.
4. Select ZenMCPRoblox/dist/extension/.
5. Pin ZenMCPRoblox to the browser toolbar if desired.

The generated dist/extension/config.json contains your local bridge token. It is ignored by Git and must not be published or shared.

Everyday use

Start everything ZenMCPRoblox controls with one command:

npm run start

Keep that terminal open. Then:

1. Open a place in Roblox Studio and wait for the MCP plugin to connect.
2. Open a supported AI website and refresh the tab after extension updates.
3. Open the ZenMCP popup and verify the bridge, backend, and Studio statuses.
4. Leave Safe Mode enabled for inspection, or enable Edit Mode for writes.
5. Click Start session in the floating ZenMCP panel.
6. Ask the AI to inspect, debug, test, or modify the open place.

Drag the floating panel by its header. Its position is remembered independently for each provider. Chrome's toolbar popup itself is browser-anchored and cannot be moved by an extension.

Commands

Command	Purpose
npm run setup	Update dependencies/backend, install the plugin, build, diagnose
npm run start	Start the upstream backend, controller, and localhost bridge
npm run doctor	Check Node, configuration, build, plugin, bridge, and Studio
npm run build	Compile TypeScript and build dist/extension/
npm test	Run unit and local integration tests
npm run test:live	Run the opt-in real Studio read/edit/rollback test
npm run mcp	Expose ZenMCP as a native stdio MCP server
npm run safe	Persist Safe Mode for the next process start
npm run edit	Persist Edit Mode for the next process start

The same CLI is available after installation through commands such as:

npm exec zenmcp -- doctor
npm exec zenmcp -- start
npm exec zenmcp -- mcp

Safe Mode and Edit Mode

Safe Mode is the default. Known reads such as hierarchy inspection, documentation retrieval, searches, and status checks are allowed. Write, destructive, playtest, import, upload, and unfamiliar newly discovered commands are blocked.

Edit Mode allows controller-classified writes. It does not enable arbitrary OS commands or JavaScript evaluation in the browser. Unknown future upstream commands fail closed as writes until ZenMCP can classify them safely.

Browser protocol

The extension accepts only an exact block like this from the current AI session:

<zenmcp-action>
{"v":1,"id":"session-nonce:1","method":"tools/call","params":{"name":"get_place_info","arguments":{}}}
</zenmcp-action>

Security checks include:

• A random per-session action ID prefix.
• Exact protocol version and method allowlist.
• Schema validation and rejection of extra fields.
• No eval, arbitrary JavaScript, shell, or unrestricted file command.
• Authenticated local bridge requests with request IDs and timeouts.
• Rate limiting, payload limits, heartbeat checks, and structured errors.
• Asset URL/path validation.
• Controller-side Safe/Edit enforcement regardless of what the page requests.

Roblox documentation

The upstream backend exposes get_roblox_docs and get_roblox_skills tools. ZenMCP instructs the AI to consult these before assuming uncertain Roblox classes, members, services, or Luau behavior. The popup and floating panel also link to the official Roblox Engine API reference.

Upstream updates

ZenMCP discovers the installed backend's tool catalogue every time it starts. The browser fetches the current catalogue each time Start session is pressed.

To install a newly published Chrrxs backend and matching plugin:

# Stop npm run start first
npm run setup
# Fully restart Roblox Studio if the plugin changed
npm run start

Ordinary added, removed, or schema-updated upstream tools require no extension change. A breaking MCP protocol change or rename of a command used by a ZenMCP composite may require a ZenMCP compatibility update.

Generated model placement

The upstream generate_model operation intentionally stages generated models under game.ServerStorage.__MCPGeneratedModels. ZenMCP preserves that required generation step, then reparents a successful result into game.Workspace and returns its final Workspace path.

Multi-Studio routing

Multiple connected places are discovered through the upstream backend. When more than one place is open, use get_connected_instances and supply the intended instance_id. ZenMCP forwards that identifier through normal and composite tools.

History and rollback

Write attempts are recorded as JSON Lines under .agent-history/. This directory is local and ignored by Git. zen_rollback calls the upstream undo tool, which uses Roblox Studio's change history. Rollback means undoing the most recent Studio change, not replaying an arbitrary historical snapshot.

Troubleshooting

ERR_CONNECTION_REFUSED on port 39393

Nothing is listening on the configured bridge port. Run and keep open:

npm run start

Then open http://127.0.0.1:39393/health. A running bridge returns JSON.

Bridge connected, Studio offline

• Open Roblox Studio and load a place.
• Enable Allow HTTP Requests.
• Confirm the installed MCP plugin reports Connected.
• Fully restart Studio after plugin updates.
• Run npm run doctor for an actionable diagnosis.

Extension changed but the page looks old

1. Open chrome://extensions.
2. Click Reload on ZenMCPRoblox.
3. Refresh every supported AI tab.

Edit Mode does not enable

Edit Mode is stored in the running controller. Verify Local Bridge and Roblox MCP are connected, then try the toggle again. The popup displays the bridge's structured error if the mode request fails.

AI site cannot find its composer or Send control

Reload the extension and refresh the page first. Provider adapters rely on each website's current interface. If a site has changed, update its selectors in extension/src/content/provider-profiles.js and rebuild.

Testing

npm test

The default suite covers the strict extension parser, authenticated WebSocket flow, dynamic tool discovery, Safe/Edit permissions, provider configuration, service-worker recovery, Workspace model placement, native MCP exposure, edit and rollback flow, asset validation, and extension assets.

The real Studio test is opt-in because it creates a disposable object and invokes real Studio undo:

npm run test:live

It fails rather than pretending Studio is connected when the external plugin is unavailable.

Project layout

ZenMCPRoblox/
├── extension/            Chromium extension source and icon assets
├── src/
│   ├── assets/           Asset request security
│   ├── bridge/           Authenticated localhost WebSocket bridge
│   ├── cli/              setup, start, doctor, mode, and native MCP commands
│   ├── config/           Local configuration model
│   ├── context/          Result summarization
│   ├── history/          Change history
│   ├── instances/        Multi-Studio discovery/routing
│   ├── orchestration/    Composite agent tools
│   ├── permissions/      Safe/Edit risk enforcement
│   ├── server/           Controller and application composition
│   ├── tools/            Dynamic capability registry
│   ├── types/            Shared TypeScript interfaces
│   └── upstream/         Chrrxs MCP client integration
├── tests/
│   ├── integration/
│   └── unit/
├── scripts/              Build helpers
├── .env.example
├── .gitignore
├── package.json
└── tsconfig.json

Credits and acknowledgements

Chrrxs / Roblox Studio MCP

Core Roblox Studio communication is provided by @chrrxs/robloxstudio-mcp, created and maintained by Chrrxs (referred to as Chris in this project's development discussions). It supplies the MCP server, Studio plugin, edit/runtime/playtest tools, multi-instance support, official Roblox docs retrieval, and plugin installation workflow that ZenMCPRoblox controls and security-gates. The upstream project is MIT licensed.

ZenMCPRoblox depends on the published npm package and does not claim authorship of the Chrrxs backend or Studio plugin.

ZeroScript-Free

The concept of isolating website-specific AI adapters behind a provider-neutral browser agent loop was inspired by ZeroScript-Free, created and maintained by sebattfg. ZeroScript demonstrated practical browser support for DeepSeek, Gemini, Kimi, GLM, Qwen, Arena, and Meta AI communicating with Roblox Studio through a local bridge.

ZeroScript-Free is GPL-3.0 licensed. ZenMCPRoblox's implementation is independent: the ZeroScript repository is used only as an excluded local reference during compatibility research, and its source is not copied or redistributed in this project.

Roblox documentation

Roblox API guidance is sourced from the Roblox Creator documentation and its Engine API reference.

Thank you to these maintainers and communities for making this project possible.

License and third-party notices

Original ZenMCPRoblox materials are distributed under the proprietary ZenMCPRoblox Reference-Only License. You may link to, cite, discuss, review, and learn from the project's ideas, but you may not copy, modify, redistribute, republish, create derivative works from, or incorporate its code, assets, documentation, or other copyrightable expression without separate prior written permission. This is not an open-source license.

Selling ZenMCPRoblox is prohibited. This includes paid downloads, subscriptions, paywalled access, marketplace listings, monetized hosting, paid bundles, rebranded copies, commercial derivatives, and donations tied to receiving or using the software. Only a separate written agreement from the copyright holder can authorize commercial use.

Copyright protects source-code expression rather than underlying ideas, methods, or systems. Clean, independently written implementations of general ideas are permitted by the license as long as they do not copy ZenMCPRoblox's protected expression.

• @chrrxs/robloxstudio-mcp: MIT License; see its upstream repository/package.
• ZeroScript-Free: GPL-3.0; credited as architectural inspiration only.
• Roblox and Roblox Studio are trademarks of Roblox Corporation.
• Other product and company names belong to their respective owners.

Review dependency licenses before redistributing binaries or making this repository public.