# hope1026/weppy-roblox-mcp [Health: Active]

**Category:** 🎮 Gaming  
**Repository:** https://github.com/hope1026/weppy-roblox-mcp  
**GitHub Stars:** 68  
**npm Downloads (last month):** 7936  
**Views:** 5  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/hope1026-weppy-roblox-mcp

## Description
MCP server and plugin that lets AI agents (Claude Code, Cursor, Codex, Gemini) directly control a live Roblox Studio session — create scripts, instances, terrain, lighting, and assets via natural language. 21 tools, 140+ actions, bidirectional sync, and automated playtest.

## Tools
Capabilities this server exposes over MCP:

- **query_instances** — Query Roblox instances: get, children, find child/descendant, wait for child, class info, search by name/class. [PRO] file_tree, project_structure, descendants, ancestors, search by property/tag.
- **mutate_instances** — Create, delete, clone, move, rename, or pivot instances. [PRO] create_tree, mass_create, mass_delete, mass_duplicate, smart_duplicate, scatter.
- **manage_properties** — Get/set properties, attributes, and tags on instances. [PRO] set_calculated, set_relative, mass_set, mass_get, modify_children.
- **manage_scripts** — Manage script source code: read, write, create, delete, edit lines, search, and validate Luau syntax. [PRO] replace across scripts.
- **manage_ui** — Create / update / verify Roblox in-game UI (ScreenGui / Frame / TextLabel / …). Always start with `design_brief`. For ambiguous input, it inspects Studio context and returns candidate brief patches; Do not dump enum lists at the user. An empty StarterGui does not prove runtime UI absence: for an existing-UI review, follow `runtime_review_required`, collect a structured Play Client PlayerGui snapshot, and pass its saved `runtimeEvidenceRef`. Pass relevant repository evidence in `projectContext`; explicit screen job, visual thesis, forbidden defaults, tokens, and approved assets determine the direction without a built-in subject preset. `design_brief` returns a primary-view-first Design Contract and an advisory Layout Plan with neutral regions, AnchorPoint strategy, and responsive behavior; it is not a hard tree preset or style quota. A calling agent may declare provider-neutral image generation capability through `agentCapabilities`; missing or unavailable capability must use the explicit existing, user-provided, Creator Store, or assetless fallback. Keep the returned `brief_id`, `design_contract`, and `layout_plan` through creation, update, preview, and check. The asset recommendation gate considers user references, project assets, existing UI, and user-approved `manage_assets.search` intent; do not use a recommendation until the user accepts it. After each meaningful create or update, preview the representative primary view and submit a calling-agent critic verdict (`recompose`, `refine`, or `approved`) with `visualReview`. Read `primary_visual_verdict`, `functional_safe`, `responsive_requirement`, `responsive_ready`, `required_dimensions`, and `readiness` separately from mutation success. Responsive evidence blocks readiness only when the Design Contract marks it required. Read `weppy://ui-studio/guide` for the authoring workflow, `weppy://ui-studio/tokens` for optional visual examples, and `weppy://ui-studio/functional-rules` for machine-readable advisory evidence rules. Design Check permits `priority_high` only for observed functional visual failures such as meaningful overlap, unreadable content, invalid geometry, or primary-view occlusion; style-only findings remain medium or low.

- **manage_lighting** — [PRO] Configure environment: lighting, atmosphere, sky, terrain properties, time of day.
- **manage_selection** — Get, set, or clear selection. [PRO] context, details, add/remove items, watch changes.
- **manage_camera** — Camera operations: get info, focus on instance/position, suggest view, capture Edit-mode viewport screenshot (Edit mode only; not usable during playtest).
- **manage_tween** — [PRO] Tween service: create, play, pause, cancel tweens for smooth animations.
- **manage_audio** — [PRO] Audio management: play, stop, pause, resume sounds. Set audio listener.
- **manage_animation** — [PRO] Animation: load, play, stop animations. Get animation tracks from humanoid/controller.
- **manage_physics** — [PRO] Physics collision groups: register, set collidable between groups, list groups.
- **manage_effects** — [PRO] Particle effects: emit particles, clear all particles, toggle effect enabled state.
- **manage_terrain** — [PRO] Terrain operations: fill shapes, clear regions, replace materials, manage colors, read/write voxels, generate procedural terrain, smooth terrain.
- **spatial_query** — [PRO] Spatial queries: raycast, find ground, check placement, multi-raycast, scan area, find flat areas, find spawn positions, analyze walkable, spatial map, find empty space, get bounds, snap to grid, check collision.
- **manage_assets** — [PRO] Asset management: insert models by ID, get asset info, search creator store, insert free models/packages, export selection JSON, generate/review Roblox models, round-trip .rbxm files through Asset Library, and generate local thumbnails.
- **manage_open_cloud_assets** — [PRO] Roblox Open Cloud asset upload: preflight diagnostics, credential status, category capabilities, Asset Library-backed upload, existing asset linking, updates, metadata reads, and operation polling. Does not expose delete/archive/restore actions.
- **manage_sync** — [PRO] Project sync management: status, history, effective policy, and synced file access.
- **workspace_state** — [PRO] Workspace state: full sync, snapshot, recent changes, viewport info, clear history, metadata, scripts, selection info, clear cache.
- **manage_logs** — Output logs: get filtered logs, poll incrementally with sinceSeq cursor, clear buffer, get recent errors.
- **manage_settings** — WEPPY settings management. Read or change whether Dashboard opens automatically when the MCP Server starts.
- **system_info** — System info: ping, connection status, usage tier, and read-only Studio preflight diagnostics. [PRO] place info and services list.
- **manage_studio** — Prepare Playtest values on Basic, and control Roblox Studio playtest lifecycle, automated test runs, runtime values, and editor view/rendering QA workflows on Pro.

- **batch_execute** — [PRO] Execute multiple commands in a single batch. Each command is an object with "tool" name and "args". Commands execute sequentially; optionally continue on error.
- **execute_luau** — [PRO] Execute arbitrary Luau code in Roblox Studio sandbox. Blocked services: HttpService, DataStoreService, MessagingService. Cannot access CoreGui/CorePackages.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "weppy-roblox-mcp": {
    "command": "npx",
    "args": ["-y","@weppy/roblox-mcp@latest"]
  }
}
```

## Documentation

## What hope1026/weppy-roblox-mcp does

hope1026/weppy-roblox-mcp links an MCP client with the WEPPY Roblox Studio Plugin so an AI agent can inspect and change a live Roblox project. The exposed operations cover the Roblox DataModel, Luau source, properties, attributes, tags, UI, terrain, lighting, selection, camera state, logs, assets, and Studio playtest control.

The server is suited to workflows such as building a game scene, updating related scripts, placing collision-safe spawn points, reviewing runtime output, or preparing assets for use in a Place. It can also work across multi-Place projects: up to five Studio windows can be connected, and requests can target a particular Studio ID.

## How it works

The MCP server runs locally and communicates with the WEPPY Roblox Studio Plugin. The plugin provides the live Studio connection through which tool requests are applied and state is read back. Changes can be reflected in Studio and the dashboard, while synchronization tools expose project status, history, policies, and synced files.

UI authoring follows a structured workflow. The agent begins with a design brief, retains the returned brief and layout data through creation and review, previews the primary view after meaningful changes, and submits a visual review verdict. Runtime UI checks can use a saved PlayerGui snapshot. Studio control also includes playtest lifecycle operations, runtime values, automated tests, and editor rendering or view checks on the Pro tier.

## Setup and configuration

Requirements include Node.js 22 or newer, Roblox Studio, and Windows 10 or newer or macOS 12 or newer. Install the package directly with:

```bash
npx -y @weppy/roblox-mcp@latest
```

The project also provides one-line installers for macOS/Linux and Windows PowerShell, plus a browser-based installer. These installers can register the server with supported clients and can install the optional WEPPY AI Agent Plugin for selected clients.

The server uses a local STDIO connection. Roblox Studio must be running with the WEPPY plugin connected. For multi-Place work, connect the relevant Studio windows and use their Studio IDs when directing operations.

## Tools and capabilities

Core tool groups include:

- Querying, creating, deleting, cloning, moving, renaming, and pivoting Roblox instances.
- Reading and changing properties, attributes, and tags, including batch operations on the Pro tier.
- Reading, writing, creating, deleting, editing, searching, and syntax-validating Luau scripts.
- Creating, updating, previewing, and checking Roblox UI through the UI Studio workflow.
- Managing lighting, terrain, particles, audio, animations, physics collision groups, tweens, cameras, and selection.
- Searching and inserting Creator Store assets, handling local Asset Library files, uploading through Roblox Open Cloud, and applying returned asset URIs.
- Inspecting workspace state, synchronized files, logs, connection status, settings, and Studio diagnostics.
- Running sequential batches of commands and executing Luau in the Studio sandbox on the Pro tier.

## Limitations and notes

Several tool groups and advanced actions are marked Pro, including terrain editing, asset management, spatial queries, synchronization, batch execution, and arbitrary Luau execution. The Luau sandbox blocks HttpService, DataStoreService, and MessagingService, and cannot access CoreGui or CorePackages. Camera screenshots are available only in Edit mode and cannot be captured during playtest. Open Cloud asset management supports upload, linking, updates, metadata, and operation polling, but not delete, archive, or restore actions.

_Full upstream README: https://allmcps.com/mcp/hope1026-weppy-roblox-mcp/readme_