BloxForge

Give AI coding agents a safe, local interface to Roblox Studio.

Inspect places, edit Luau, build worlds, run playtests, and debug live sessions from any MCP-compatible client.

Get started · Explore tools · Troubleshoot · Telegram

---

Roblox Studio, controlled by your agent

BloxForge connects an MCP client to a lightweight Studio plugin over localhost:

Claude Code / Codex / Cursor / Gemini
                  ↕ MCP
          BloxForge Node server
                  ↕ localhost
          Roblox Studio plugin

No BloxForge cloud account is required. Your place data and bridge traffic stay on your machine.

	What BloxForge provides
Build	Instances, UI, terrain, lighting, templates, reusable models, and generated scenes
Code	Read, search, patch, validate, and safely replace Luau source
Test	Playtests, simulated input, gameplay assertions, screenshots, and episode comparison
Debug	Runtime logs, transport diagnostics, memory data, breakpoints, and profiler captures
Integrate	Rojo-aware project tools, imports/exports, asset workflows, and provenance records
Protect	Localhost binding, scoped capabilities, confirmation gates, dry runs, limits, and recovery

Quick start

Requires Node.js 20 or newer.

1. Allow Studio HTTP requests

In Roblox Studio, open Game Settings → Security and enable Allow HTTP Requests.

2. Install the Studio plugin

Run this once, and again whenever you update BloxForge:

npx -y @princeofscale/bloxforge@latest --install-plugin

Fully close and reopen Roblox Studio after installing or updating the plugin.

3. Connect your MCP client

Claude Code

claude mcp add bloxforge -- npx -y @princeofscale/bloxforge@latest

Codex CLI

codex mcp add bloxforge -- npx -y @princeofscale/bloxforge@latest

Gemini CLI

gemini mcp add bloxforge npx --trust -- -y @princeofscale/bloxforge@latest

Cursor

Add this to .cursor/mcp.json:

{
  "mcpServers": {
    "bloxforge": {
      "command": "npx",
      "args": ["-y", "@princeofscale/bloxforge@latest"]
    }
  }
}

Use @next instead of @latest to test release candidates.

MCP clients normally start BloxForge before Roblox Studio. The message Waiting for Studio plugin to connect... means the server is healthy and idle. Open a Studio project whenever you are ready.

4. Verify everything

Start your MCP client, open a place in Studio, and run:

npx -y @princeofscale/bloxforge@latest verify

Try it

Start with a focused request:

Inspect this place, summarize its architecture, identify runtime risks, and propose a safe implementation plan before changing anything.

Or let the agent execute an end-to-end workflow:

Build a six-stage obby with checkpoints and a timer, playtest it, inspect the runtime logs, and fix any errors you find.

Choose the right tool profile

Profiles keep tool discovery focused and reduce context use:

Profile	Best for
core	Everyday inspection, scripts, and essential editing — the default discovery set
builder	UI, terrain, templates, assets, and scene construction; arbitrary Luau execution denied
tester	Playtests, runtime debugging, input simulation, and assertions
full	Every available BloxForge tool
inspector	Read-only authorization; the dedicated @princeofscale/bloxforge-inspector also omits write definitions

Select one with --profile <name> or BLOXFORGE_TOOL_PROFILE. Profiles control authorization where stated; load_toolset only expands schema visibility and cannot grant a denied tool. Invalid names fail startup.

Reliability and safety

BloxForge treats Studio as a recoverable local execution target:

• request acknowledgements, delivery leases, deduplication, and status lookup;
• safe retry rules that distinguish reads from mutations;
• explicit outcome_unknown handling after interrupted operations;
• bounded atomic recovery journals and payload-free p50/p95/p99 diagnostics;
• authenticated proxy forwarding with queryable primary request IDs;
• per-DataModel concurrency limits and backpressure;
• plugin session credentials and capability-scoped MCP clients;
• localhost-only bridge binding by default, with authenticated non-loopback opt-in;
• mutation confirmation, dry-run, backup, and rollback-oriented tools.

See Architecture and Security policy for the full model.

Optional Roblox Open Cloud access

Most features need no Roblox credentials. Creator Store access and asset uploads can use an optional Open Cloud API key with the required asset scopes:

export ROBLOX_OPEN_CLOUD_API_KEY="your-api-key"

Never commit the key or place it in shared MCP configuration.

Develop locally

npm ci
npm run build:all
npm test
npm run lint

Plugin builds only write repository artifacts. Set MCP_PLUGINS_DIR to an explicit temporary directory when testing installation; builds never infer or modify your normal Studio plugin directory.

Useful release checks:

npm run test:plugin:smoke
npm run test:plugin:installer
npm run docs:check
npm run verify-package

Documentation

• Tool reference
• Architecture
• Known limitations
• Troubleshooting
• Security policy
• Changelog

Community

• Releases and project news: official Telegram channel
• Bugs and feature requests: GitHub Issues
• Security reports: follow the private process in SECURITY.md

License

MIT © BloxForge contributors.