{"_id":"@aaronalm19/roblox-mcp","name":"@aaronalm19/roblox-mcp","dist-tags":{"latest":"1.10.0"},"versions":{"1.10.0":{"name":"@aaronalm19/roblox-mcp","version":"1.10.0","description":"MCP Server for Roblox Studio Integration - Access Studio data, scripts, and objects through AI tools","main":"dist/index.js","type":"module","bin":{"roblox-mcp":"dist/index.js"},"scripts":{"build":"tsc","build:plugin":"node scripts/build-plugin.mjs","build:all":"npm run build && npm run build:plugin","places":"node scripts/places.mjs","place:detect":"node scripts/places.mjs detect --init-if-missing --set-active","place:list":"node scripts/places.mjs list","place:status":"node scripts/places.mjs status","blueprint:doctor":"node scripts/blueprint-doctor.mjs","blueprint:sync":"node scripts/sync-roblox-properties.mjs","blueprint:watch":"node scripts/watch-roblox-properties.mjs","blueprint:reverse-sync":"node scripts/reverse-sync-rojo.mjs","push:fast":"node scripts/push-script-fast.mjs","push:diff":"node scripts/push-script-diff.mjs","apply:verify":"node scripts/apply-verify.mjs","drift:check":"node scripts/check-drift.mjs","lint:deprecated":"node scripts/lint-deprecated-apis.mjs","luau:install":"node scripts/install-luau-cli.mjs","luau:lint":"node scripts/luau-lint.mjs","luau:lint:strict":"node scripts/luau-lint.mjs --strict --fail-on-findings","dev:cockpit":"node scripts/dev-cockpit.mjs","dev:studio":"node scripts/dev-studio.mjs --with-rojo --with-watch --with-reverse","telemetry:once":"node scripts/telemetry-dashboard.mjs --once","telemetry:watch":"node scripts/telemetry-dashboard.mjs","test:live":"node scripts/live-smoke.mjs","dev":"tsx src/index.ts","start":"node dist/index.js","lint":"eslint src/**/*.ts","typecheck":"tsc --noEmit","test":"jest","test:watch":"jest --watch","test:coverage":"jest --coverage","test:e2e":"lune run tests/luau/e2e.luau","test:all":"npm test && npm run test:e2e","prepublishOnly":"npm run build:all"},"keywords":["mcp","roblox","studio","ai","model-context-protocol","game-development"],"author":"","license":"MIT","repository":{"type":"git","url":"git+https://github.com/aaronaalmendarez/roblox-mcp.git"},"homepage":"https://github.com/aaronaalmendarez/roblox-mcp#readme","bugs":{"url":"https://github.com/aaronaalmendarez/roblox-mcp/issues"},"dependencies":{"@modelcontextprotocol/sdk":"^0.6.0","cors":"^2.8.5","express":"^4.18.2","node-fetch":"^3.3.2","uuid":"^9.0.1","ws":"^8.14.2"},"devDependencies":{"@types/cors":"^2.8.17","@types/express":"^4.17.21","@types/jest":"^29.5.11","@types/node":"^20.10.0","@types/supertest":"^6.0.2","@types/uuid":"^9.0.7","@types/ws":"^8.5.10","@typescript-eslint/eslint-plugin":"^7.0.0","@typescript-eslint/parser":"^7.0.0","eslint":"^8.57.0","jest":"^29.7.0","supertest":"^6.3.3","ts-jest":"^29.1.1","tsx":"^4.6.0","typescript":"^5.3.2"},"gitHead":"b9f8fa19a2f8838919b359ceb3a4eb18fe5305fc","types":"./dist/index.d.ts","_id":"@aaronalm19/roblox-mcp@1.10.0","_nodeVersion":"24.11.1","_npmVersion":"11.6.2","dist":{"integrity":"sha512-EJqFWFwhk0xcOiXGPt/pVjlLY7SttqTQw9nYF/+qujJxjf7T5rFnhXOEoL+KsuJTk64YdXSXANQEbeqKTRkLLA==","shasum":"8c8e8d6c5f76741988509e1f9f4e5023d607f61a","tarball":"https://registry.npmjs.org/@aaronalm19/roblox-mcp/-/roblox-mcp-1.10.0.tgz","fileCount":44,"unpackedSize":609431,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCTe/GS3UveL6YfSQjVp7b42bOJ9amUl6/Bz7wesmb/TgIgE37IOGAxkb8Rhez6UytgYtWrXuL/gdaKhOomueg8q2U="}]},"_npmUser":{"name":"aaronalm19","email":"aaronaalmendarez@gmail.com"},"directories":{},"maintainers":[{"name":"aaronalm19","email":"aaronaalmendarez@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/roblox-mcp_1.10.0_1770809654261_0.7870527984471956"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-11T11:34:14.192Z","1.10.0":"2026-02-11T11:34:14.418Z","modified":"2026-02-11T11:34:14.762Z"},"maintainers":[{"name":"aaronalm19","email":"aaronaalmendarez@gmail.com"}],"description":"MCP Server for Roblox Studio Integration - Access Studio data, scripts, and objects through AI tools","homepage":"https://github.com/aaronaalmendarez/roblox-mcp#readme","keywords":["mcp","roblox","studio","ai","model-context-protocol","game-development"],"repository":{"type":"git","url":"git+https://github.com/aaronaalmendarez/roblox-mcp.git"},"bugs":{"url":"https://github.com/aaronaalmendarez/roblox-mcp/issues"},"license":"MIT","readme":"

\n \"Roblox\n

\n\n

Roblox Studio MCP

\n\n

\n Model Context Protocol server for AI-powered Roblox Studio development\n

\n\n

\n \"npm\n \"MIT\n \"Node.js\"\n \"Issues\"\n

\n\n

\n Quick Start •\n Features •\n Architecture •\n Tools •\n Client Setup •\n Blueprint •\n Contributing\n

\n\n---\n\n## What Is This?\n\n**Roblox Studio MCP** bridges any MCP-compatible AI assistant — Claude, Gemini, Codex, OpenCode, and more — directly into a running Roblox Studio session. Your AI can read the instance tree, edit scripts, set properties, manage attributes and tags, create objects, and sync source files — all through a local, privacy-first connection that never leaves your machine.\n\n## 🚀 Quick Start\n\n### 1. Install the Studio Plugin\n\nInstall the plugin manually from this repository (see below).\n\n
\nAlternative methods\n\n**Direct download:**\nDownload [MCPPlugin.rbxmx](https://github.com/boshyxd/robloxstudio-mcp/releases/latest/download/MCPPlugin.rbxmx) and save to your plugins folder:\n- **Windows:** `%LOCALAPPDATA%/Roblox/Plugins/`\n- **macOS:** `~/Documents/Roblox/Plugins/`\n\n**From source:**\n```bash\nnpm run build:plugin\n# Copy studio-plugin/MCPPlugin.rbxmx to your plugins folder\n```\n
\n\n### 2. Enable HTTP in Studio\n\n**Game Settings → Security → Allow HTTP Requests** ✅\n\n### 3. Connect Your AI Client\n\n```bash\n# This fork / local harness\nnode dist/index.js\n```\n\nNote: `npx -y robloxstudio-mcp@latest` runs the upstream npm package from `boshyxd/robloxstudio-mcp`, not this fork.\n\n## ✨ Features\n\n### 37+ MCP Tools\n\n| Category | What It Does |\n| ---------------------- | -------------------------------------------------------------------------- |\n| **Instance Hierarchy** | Browse the full game tree, search by name/class/content, explore services |\n| **Script Management** | Read, write, and edit Luau scripts with line-level precision |\n| **Batch Editing** | Atomic multi-operation edits with hash checks and automatic rollback |\n| **Properties** | Get/set any instance property, mass operations, formula-based calculations |\n| **Object Lifecycle** | Create, delete, and smart-duplicate instances with property variations |\n| **Attributes & Tags** | Full CRUD for instance attributes and CollectionService tags |\n| **Diagnostics** | Drift detection, deprecated API linting, health monitoring, telemetry |\n| **Snapshots** | In-memory script snapshots with rollback for safe experimentation |\n\n### IDE-First Workflow\n\n- **Blueprint V1** — Rojo-based source control with multi-place project support\n- **Bi-directional sync** — Push files to Studio or pull Studio changes back to disk\n- **Conflict resolution** — Hash-based safeguards prevent accidental overwrites\n- **Drift detection** — Detect when Studio and local files have diverged\n\n### Reliability & Performance\n\n- Optimistic concurrency with SHA-256 hash checks\n- Write idempotency (replay-safe via `X-Idempotency-Key`)\n- Fast write paths for large scripts (gzip support)\n- Smart plugin polling with hot/active/idle intervals\n- Atomic apply-verify-rollback pipeline\n\n## 🏗️ Architecture\n\n```\n┌─────────────────┐ stdio ┌─────────────────┐ HTTP ┌─────────────────┐\n│ AI Assistant │ ◄──────────────► │ MCP Server │ ◄───────────► │ Studio Plugin │\n│ (Claude, Gemini, │ │ (Node.js) │ localhost │ (Luau) │\n│ Codex, etc.) │ │ Port 3002 │ :3002 │ Polls for work │\n└─────────────────┘ └─────────────────┘ └─────────────────┘\n │\n ▼\n ┌─────────────────┐\n │ Blueprint V1 │\n │ (Rojo project │\n │ + sync tools) │\n └─────────────────┘\n```\n\n| Component | Location | Purpose |\n| ----------------- | -------------------- | --------------------------------------------------------------- |\n| **MCP Server** | `src/` | TypeScript server implementing the MCP protocol over stdio |\n| **HTTP Bridge** | `src/http-server.ts` | Express server on `:3002` bridging MCP ↔ Studio plugin |\n| **Studio Plugin** | `studio-plugin/` | Luau plugin that polls the bridge and executes Studio API calls |\n| **Blueprint** | `blueprint-v1/` | Rojo project trees, property manifests, and sync state |\n| **CLI Scripts** | `scripts/` | 20+ helper scripts for sync, lint, push, diagnostics |\n\n## 🔧 MCP Tools\n\n
\nInstance Hierarchy — Browse and search the game tree\n\n| Tool | Description |\n| ----------------------- | ----------------------------------------------------- |\n| `get_file_tree` | Get the Roblox instance hierarchy as a tree |\n| `search_files` | Search instances by name, class, or script content |\n| `get_services` | List available Roblox services and their children |\n| `search_objects` | Find instances by name, class, or property value |\n| `get_project_structure` | Get complete game hierarchy with configurable depth |\n| `get_instance_children` | Get child instances and their class types |\n| `get_class_info` | Get available properties/methods for any Roblox class |\n| `get_place_info` | Get place ID, name, and game settings |\n| `get_selection` | Get currently selected objects in Studio |\n
\n\n
\nScript Management — Read, write, and edit Luau scripts\n\n| Tool | Description |\n| -------------------------------- | ------------------------------------------------------ |\n| `get_script_source` | Read script source with optional line ranges |\n| `get_script_snapshot` | Get source + SHA-256 hash for concurrency control |\n| `set_script_source` | Replace entire script source (editor-safe) |\n| `set_script_source_checked` | Write only if hash matches (prevents stale overwrites) |\n| `set_script_source_fast` | Direct assignment for large scripts |\n| `set_script_source_fast_gzip` | Gzip-compressed fast write for very large scripts |\n| `edit_script_lines` | Replace specific line ranges |\n| `insert_script_lines` | Insert lines at a specific position |\n| `delete_script_lines` | Delete specific line ranges |\n| `batch_script_edits` | Atomic multi-edit with rollback and hash check |\n| `apply_and_verify_script_source` | Atomic apply → verify → rollback pipeline |\n
\n\n
\nSnapshots & Safety — Rollback protection\n\n| Tool | Description |\n| -------------------------- | ----------------------------------------- |\n| `create_script_snapshot` | Create an in-memory rollback point |\n| `list_script_snapshots` | List all snapshots in the current session |\n| `rollback_script_snapshot` | Restore source from a snapshot |\n| `cancel_pending_writes` | Cancel queued write operations |\n
\n\n
\nProperties & Objects — Modify instances and create new ones\n\n| Tool | Description |\n| ------------------------------------- | ------------------------------------------------------- |\n| `get_instance_properties` | Get all properties of an instance |\n| `set_property` | Set a property on any instance |\n| `mass_set_property` | Set the same property on multiple instances |\n| `mass_get_property` | Read the same property from multiple instances |\n| `search_by_property` | Find objects with specific property values |\n| `set_calculated_property` | Set properties using mathematical formulas |\n| `set_relative_property` | Modify properties relative to current values |\n| `create_object` | Create a new instance |\n| `create_object_with_properties` | Create an instance with initial properties |\n| `mass_create_objects` | Batch-create multiple instances |\n| `mass_create_objects_with_properties` | Batch-create with properties |\n| `delete_object` | Delete an instance |\n| `smart_duplicate` | Duplicate with auto-naming, positioning, and variations |\n| `mass_duplicate` | Multiple smart duplications at once |\n
\n\n
\nAttributes & Tags — Instance metadata\n\n| Tool | Description |\n| --------------------------------- | -------------------------------------- |\n| `get_attribute` / `set_attribute` | Read/write a single attribute |\n| `get_attributes` | Get all attributes on an instance |\n| `delete_attribute` | Remove an attribute |\n| `get_tags` | Get all CollectionService tags |\n| `add_tag` / `remove_tag` | Add or remove a tag |\n| `get_tagged` | Find all instances with a specific tag |\n
\n\n
\nDiagnostics & Quality — Monitor and lint\n\n| Tool | Description |\n| ---------------------- | --------------------------------------------- |\n| `get_runtime_state` | Get write queue and bridge telemetry |\n| `get_diagnostics` | Full diagnostics: queue, snapshots, readiness |\n| `check_script_drift` | Compare local files vs Studio source hashes |\n| `lint_deprecated_apis` | Scan for deprecated Roblox API usage |\n
\n\n## 🔌 Client Setup\n\nWorks with **any MCP-compatible client**.\n\nFor this fork/local workspace:\n\n```bash\nnode C:/Users/aaron/OneDrive/Desktop/rblxMCP/dist/index.js\n```\n\nYour published package (this fork):\n\n```\nnpx -y @aaronalm19/roblox-mcp@latest\n```\n\nUpstream package (original project):\n\n```\nnpx -y robloxstudio-mcp@latest\n```\n\n
\nClaude Code\n\n```bash\nclaude mcp add robloxstudio -- node C:/Users/aaron/OneDrive/Desktop/rblxMCP/dist/index.js\n```\n
\n\n
\nGemini CLI\n\n```bash\ngemini mcp add robloxstudio node --trust -- C:/Users/aaron/OneDrive/Desktop/rblxMCP/dist/index.js\n```\n
\n\n
\nClaude Desktop / mcpServers JSON\n\n```json\n{\n \"mcpServers\": {\n \"robloxstudio-mcp\": {\n \"command\": \"node\",\n \"args\": [\"C:/Users/aaron/OneDrive/Desktop/rblxMCP/dist/index.js\"]\n }\n }\n}\n```\n
\n\n
\nCodex CLI\n\n`~/.codex/config.toml`:\n```toml\n[mcp_servers.robloxstudio]\ncommand = \"node\"\nargs = [\"C:/Users/aaron/OneDrive/Desktop/rblxMCP/dist/index.js\"]\n```\n
\n\n
\nOpenCode\n\n`~/.config/opencode/opencode.json`:\n```json\n{\n \"mcp\": {\n \"robloxstudio\": {\n \"type\": \"local\",\n \"enabled\": true,\n \"command\": [\"node\", \"C:/Users/aaron/OneDrive/Desktop/rblxMCP/dist/index.js\"]\n }\n }\n}\n```\n
\n\n
\nWindows troubleshooting\n\nIf your client cannot launch `node` directly, wrap with `cmd`:\n```json\n{\n \"command\": \"cmd\",\n \"args\": [\"/c\", \"node\", \"C:/Users/aaron/OneDrive/Desktop/rblxMCP/dist/index.js\"]\n}\n```\n
\n\n## 📘 Blueprint V1\n\nBlueprint V1 is the IDE-first source control layer built on [Rojo](https://rojo.space/). It enables bi-directional sync between your local files and Roblox Studio.\n\n### Multi-Place Projects\n\n```\nblueprint-v1/\n├── places/\n│ ├── registry.json # Place ID → slug mapping\n│ ├── .active-place.json # Currently active place\n│ └── /\n│ ├── default.project.json # Rojo project file\n│ ├── src/ # Luau source tree\n│ └── properties/\n│ └── instances.json # Non-script property manifest\n└── src/ # Legacy fallback tree\n```\n\n### Key Commands\n\n```bash\n# Place management\nnpm run place:detect # Auto-detect and register current Studio place\nnpm run place:list # List all registered places\nnpm run place:status # Show resolved project/src paths\n\n# Sync\nnpm run blueprint:sync # One-shot property sync (Studio → manifest)\nnpm run blueprint:watch # Continuous property sync\nnpm run blueprint:reverse-sync # Pull Studio changes back to local files\n\n# Quality\nnpm run blueprint:doctor # Connectivity diagnostics\nnpm run drift:check # Detect file drift between local and Studio\nnpm run lint:deprecated # Scan for deprecated API usage\nnpm run luau:lint # Luau static analysis\nnpm run luau:lint:strict # Strict mode analysis\n```\n\n## 🛠️ Development\n\n### Prerequisites\n\n- **Node.js** ≥ 18\n- **Roblox Studio** with HTTP requests enabled\n- **Rojo** (recommended, for script syncing)\n\n### Build & Test\n\n```bash\nnpm install # Install dependencies\nnpm run build # Compile TypeScript → dist/\nnpm run build:plugin # Build Studio plugin .rbxmx\nnpm run typecheck # Type-check without emitting\nnpm test # Run Jest test suite\nnpm run luau:lint # Lint Luau source files\n```\n\n### Run Locally\n\n```bash\nnpm run dev # Start with tsx (hot reload)\nnpm start # Start from compiled dist/\n```\n\n### Health Check\n\n```bash\n# Verify the server and plugin are connected\ncurl http://localhost:3002/health\ncurl http://localhost:3002/status\ncurl http://localhost:3002/diagnostics\n```\n\n### Project Structure\n\n```\nrobloxstudio-mcp/\n├── src/ # TypeScript MCP server source\n│ ├── index.ts # MCP tool definitions and request handler\n│ ├── http-server.ts # Express bridge server (port 3002)\n│ ├── bridge-service.ts # Plugin communication layer\n│ └── tools/ # Tool implementation modules\n├── studio-plugin/ # Roblox Studio Luau plugin\n│ ├── plugin.server.luau # Plugin source (polls bridge for work)\n│ └── MCPPlugin.rbxmx # Built plugin file\n├── blueprint-v1/ # Rojo project trees and sync state\n├── scripts/ # CLI helper scripts (sync, lint, push, etc.)\n├── tests/ # Jest + Luau E2E tests\n└── docs/ # Additional documentation\n```\n\n## 🔒 Security & Privacy\n\n- **100% local** — all communication stays on `localhost`, nothing is sent externally\n- **No data collection** — your projects, scripts, and Studio data remain private\n- **Explicit actions only** — tools run only when invoked by your MCP client\n- **Read/write separation** — read and write tools are distinct and intentional\n\n## ❓ Troubleshooting\n\n| Problem | Solution |\n| ---------------------------- | ------------------------------------------------------------------------ |\n| Plugin not in toolbar | Verify plugin file is in the correct plugins folder, restart Studio |\n| HTTP 403 errors | Enable **Allow HTTP Requests** in Game Settings → Security |\n| Plugin shows disconnected | Normal when server isn't running — start the MCP server |\n| No tools in AI client | Restart your MCP client and Studio, check `http://localhost:3002/health` |\n| Large script writes are slow | Use `set_script_source_fast` or `scripts/push-script-fast.mjs` |\n| Firewall blocking | Allow `localhost:3002` through Windows Firewall |\n\n## 📚 Additional Docs\n\n- [Client Configurations](docs/CLIENTS.md) — Setup for all supported MCP clients\n- [Blueprint V1 Guide](docs/BLUEPRINT_V1.md) — Deep dive into the sync system\n- [Plugin Installation](studio-plugin/INSTALLATION.md) — Detailed plugin setup\n\n## 🤝 Contributing\n\nContributions are welcome! Please open an issue or pull request on [GitHub](https://github.com/aaronaalmendarez/roblox-mcp).\n\n```bash\n# Development workflow\ngit clone https://github.com/aaronaalmendarez/roblox-mcp.git\ncd roblox-mcp\nnpm install\nnpm run dev\n```\n\n## 🙌 Acknowledgements\n\n- Original project: [`boshyxd/robloxstudio-mcp`](https://github.com/boshyxd/robloxstudio-mcp)\n- This repository extends that foundation for multi-agent workflows (Codex/OpenCode and local blueprint-first development).\n\n## 📄 License\n\n[MIT](LICENSE) © 2025\n","readmeFilename":"README.md","_rev":"1-c6583184e6f2c708f25e36121e6dd98b"}