# Weppy Roblox MCP — MCP Server for Roblox Studio

> Weppy Roblox MCP is an MCP server that lets AI coding agents (Claude, Codex,
> Cursor, Gemini) control a live Roblox Studio session — create and edit scripts,
> instances, terrain, lighting, assets, audio, and animations via natural language.

## What it does

Weppy Roblox MCP provides a real-time bridge between AI agents and the Roblox
Studio DataModel. It exposes the full Roblox API surface as executable MCP tools,
so AI can directly create, read, modify, and delete instances, scripts, properties,
terrain, and more — inside a live Studio session.

- 21 consolidated tools with 140+ actions covering the full Roblox Studio API surface
- Bidirectional project sync between Roblox Studio and local files (Pro)
- Automated playtest: AI starts/stops Play/Run, injects test scripts, collects logs
- Web dashboard: monitor AI actions, tool history, sync state, and changelog in real time at `http://localhost:3002`
- Multi-place support (up to 3 places simultaneously)
- Roblox Explorer VSCode extension for browsing Studio hierarchy
- Works with Claude Code, Claude Desktop, Cursor, Codex CLI, Codex Desktop, Gemini CLI, Antigravity

## Installation

**One-line install** (installs MCP server, Roblox Studio plugin, and registers with AI apps):

```bash
# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/hope1026/weppy-roblox-mcp/main/install.sh | bash

# Windows (PowerShell)
irm https://raw.githubusercontent.com/hope1026/weppy-roblox-mcp/main/install.ps1 | iex
```

Or manually:
1. Install Roblox Studio plugin (bridge between Studio and AI)
2. Register MCP server: `npx -y @weppy/roblox-mcp`

## Tiers

- Basic (Free): MCP tool execution + one-way Studio -> Local sync
- Pro: Bidirectional sync, bulk actions, terrain generation, spatial analysis, multi-place support, advanced tools

## Detailed docs

- Full documentation: [llms-full.txt](https://github.com/hope1026/weppy-roblox-mcp/blob/main/llms-full.txt)
- Installation: https://github.com/hope1026/weppy-roblox-mcp/blob/main/docs/en/installation/README.md
- Tools reference: https://github.com/hope1026/weppy-roblox-mcp/blob/main/docs/en/tools/overview.md
- Sync guide: https://github.com/hope1026/weppy-roblox-mcp/blob/main/docs/en/sync/overview.md
- Dashboard guide: https://github.com/hope1026/weppy-roblox-mcp/blob/main/docs/en/dashboard/overview.md
- Troubleshooting: https://github.com/hope1026/weppy-roblox-mcp/blob/main/docs/troubleshooting.md
- Compatibility: https://github.com/hope1026/weppy-roblox-mcp/blob/main/docs/compatibility.md
- Pro upgrade: https://github.com/hope1026/weppy-roblox-mcp/blob/main/docs/en/pro-upgrade.md

## Requirements

- Node.js >= 18
- Roblox Studio (Windows 10+ or macOS 12+)
- Any MCP-compatible AI client

## Optional

- Roblox Explorer VSCode extension (browse synced instance tree)
- Pro subscription for bidirectional sync and advanced tools

## Links

- GitHub: https://github.com/hope1026/weppy-roblox-mcp
- npm: https://www.npmjs.com/package/@weppy/roblox-mcp
- Issues: https://github.com/hope1026/weppy-roblox-mcp/issues
- Discussions: https://github.com/hope1026/weppy-roblox-mcp/discussions
