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

**Category:** 🎮 Gaming  
**Repository:** https://github.com/hope1026/weppy-roblox-mcp  
**GitHub Stars:** 61  
**Views:** 3  
**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 a new UI task with the `design_brief` action — it accepts an omitted or partial brief, inspects Studio context, then returns a current-state summary, recommended mode/change scopes, candidate brief patches, and one user-facing confirmation or clarification question. design_brief may return asset recommendation candidates from existing UI images, user references, or conservative manage_assets.search results; do not use a recommended asset until the user accepts it. Do not dump enum lists at the user; map natural language to internal purpose/platform/tone values through recommendations, and only finalize identity-defining fields after the user accepts a recommendation or provides equivalent intent. Read MCP resource `weppy://ui-studio/guide` for the full guide; it is split into Floor (non-negotiable accessibility), Vocabulary (style menu — pick ONE family per dimension; do not blend everything), Direction (brief → choices), and Tree encoding (Roblox property JSON shapes). Floor essentials suggested by Design Check (`check`): (1) mobile touch target ≥ 44 px (2) text contrast ≥ 4.5:1 (3) prefer explicit `TextSize` over `TextScaled` (4) respect platform safe zones (5) warn on full-screen opaque roots for non-modal purposes. Style is brief-driven; reject the default AI look (uniform 8 px corners + generic blue + glass card + Gotham everywhere) — each game deserves its own visual identity.

- **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, upload local files, update assets, read metadata, and poll operation status. Does not expose delete/archive/restore actions.
- **manage_sync** — [PRO] Project sync management: status, history, direction settings, read/write synced files.
- **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.
- **system_info** — System info: ping, connection status, usage tier, and read-only Studio preflight diagnostics. [PRO] place info and services list.
- **manage_studio** — Control Roblox Studio state for playtest lifecycle, automated test runs, and editor view/rendering QA workflows. Use it for state-changing playtest controls and Studio session-level View settings such as UI preview; it does not edit game UI objects or their properties.

- **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 MCP server does

The hope1026/weppy-roblox-mcp MCP server gives compatible AI clients a bridge into Roblox Studio. Its tools can inspect the DataModel, create or modify instances, manage Luau source, change properties and tags, and work with Roblox UI objects. Additional capabilities cover terrain editing, lighting, audio, animation, particles, physics collision groups, camera control, selection, logs, and workspace state.

The package also supports workflows beyond direct object editing. Agents can synchronize project files, inspect recent changes, run Studio playtests, perform rendering or editor-view checks, and use batch commands. Asset-related actions include searching the Creator Store, inserting models, handling local asset-library files, generating thumbnails, and using Roblox Open Cloud asset uploads where configured. Some listed actions are marked PRO, so availability may depend on the product tier.

## How it works

The MCP server communicates with a WEPPY Roblox Studio Plugin running in the target Studio session. The AI client sends tool calls, and the plugin applies them to the open place so changes can be reviewed in Studio. A connected setup can include up to five Studio windows, with requests directed to a selected Studio ID. This supports experiences split across places such as a lobby, shop, tutorial, and main game.

For project work, synchronization can maintain a local mirror and support different directions, including Studio-first, local-code, Studio-world, bidirectional review, and custom scopes. The initial synchronization behavior and saved settings determine which side is treated as the source. The `manage_studio` tool handles session-level state changes such as playtest controls; it is separate from editing UI objects.

## Setup and configuration

The hope1026/weppy-roblox-mcp MCP server requires Node.js 18 or newer, Roblox Studio, and Windows 10+ or macOS 12+. The README documents a manual MCP registration command:

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

The project also provides platform-specific installers and a browser-based installation page. Supported clients listed in the material include Claude Code, Claude Desktop, Cursor, Codex CLI and App, Gemini CLI, and Antigravity variants. The WEPPY Roblox Studio Plugin must be available in Roblox Studio for live control. Claude Code, Codex, and Antigravity can additionally use an optional WEPPY AI Agent Plugin for client-native workflow guidance.

## Tools and capabilities

Core tool groups include:

- Querying, creating, deleting, cloning, moving, renaming, and pivoting instances.
- Reading and writing script source, editing lines, searching scripts, and validating Luau syntax.
- Managing properties, attributes, tags, UI objects, lighting, terrain, audio, animation, effects, and physics.
- Inspecting selection, camera state, logs, connection status, workspace metadata, and sync history.
- Searching and inserting assets, exporting selection data, handling RBXM files, and uploading Open Cloud assets.
- Running sequential batches and executing Luau in a Studio sandbox.

The Luau sandbox blocks `HttpService`, `DataStoreService`, and `MessagingService`, and cannot access `CoreGui` or `CorePackages`.

## Limitations and notes

The hope1026/weppy-roblox-mcp MCP server depends on a reachable Roblox Studio session and its plugin, so it is not a standalone Roblox game-testing environment. Camera viewport capture is available only in Edit mode and cannot be used during playtest. Open Cloud asset management does not expose delete, archive, or restore actions.

UI work has a documented design workflow. New UI tasks should begin with `design_brief`, which inspects context and proposes recommendations before identity-defining choices are finalized. The UI guidance emphasizes touch targets of at least 44 pixels, text contrast of at least 4.5:1, safe zones, explicit `TextSize` where appropriate, and caution around opaque full-screen roots. Arbitrary Luau execution should be treated as constrained by the blocked services and inaccessible Core services described above.

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