Initial commit: Roblox Studio MCP Server for Claude Code
- MCP server with 12 tools for Roblox manipulation - WebSocket communication with Roblox Studio - Create scripts, parts, models, GUIs - Execute Lua code, control playtest - Full documentation and examples 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
admin
217
README.md
Normal file
217
README.md
Normal file
@@ -0,0 +1,217 @@
|
||||
# Roblox MCP Server
|
||||
|
||||
Control Roblox Studio directly from Claude Code using the Model Context Protocol (MCP).
|
||||
|
||||
## Features
|
||||
|
||||
- Create and modify scripts in Roblox Studio
|
||||
- Create 3D parts, models, and folders
|
||||
- Build GUI elements (ScreenGui, Frame, TextButton, etc.)
|
||||
- Set properties on any object
|
||||
- Get hierarchy information
|
||||
- Execute Lua code
|
||||
- Play/Stop playtesting
|
||||
- Save places
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
Claude Code <--(MCP)--> Node.js MCP Server <--(WebSocket)--> Roblox Studio Plugin
|
||||
```
|
||||
|
||||
## Installation
|
||||
|
||||
### 1. Install Node.js Dependencies
|
||||
|
||||
```bash
|
||||
cd roblox-mcp-server
|
||||
npm install
|
||||
```
|
||||
|
||||
### 2. Configure Claude Code
|
||||
|
||||
Add this to your Claude Code settings (or create `.clauderc` in your home directory):
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"roblox-studio": {
|
||||
"command": "node",
|
||||
"args": ["/mnt/c/Users/Admin/roblox-mcp-server/src/index.js"],
|
||||
"cwd": "/mnt/c/Users/Admin/roblox-mcp-server"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Install the Roblox Studio Plugin
|
||||
|
||||
#### Option A: Manual Installation
|
||||
|
||||
1. Copy `roblox-plugin/RobloxMCPServer.lua` to:
|
||||
- **Windows**: `C:\Users\YOUR_USERNAME\AppData\Local\Roblox\Plugins\RobloxMCPServer.lua`
|
||||
- **Mac**: `~/Library/Application Support/Roblox/Plugins/RobloxMCPServer.lua`
|
||||
|
||||
2. Open Roblox Studio
|
||||
|
||||
3. Go to **Plugins → Plugin Management**
|
||||
|
||||
4. Find "RobloxMCPServer" and enable it
|
||||
|
||||
#### Option B: In-Place Installation
|
||||
|
||||
1. Open Roblox Studio
|
||||
|
||||
2. Create a new place or open an existing one
|
||||
|
||||
3. In **ServerScriptService**, create a new **Script**
|
||||
|
||||
4. Paste the contents of `roblox-plugin/RobloxMCPServer.lua`
|
||||
|
||||
5. The server will auto-start when you press Play
|
||||
|
||||
### 4. Enable HTTP Requests (Important!)
|
||||
|
||||
In Roblox Studio:
|
||||
1. Go to **Game Settings → Security**
|
||||
2. **Enable** "Allow HTTP Requests"
|
||||
3. Set **Enable Studio Access to API Services** to ON
|
||||
|
||||
## Usage
|
||||
|
||||
### Starting the MCP Server
|
||||
|
||||
```bash
|
||||
npm start
|
||||
```
|
||||
|
||||
The server will start on:
|
||||
- HTTP: `http://localhost:37423` (for health checks)
|
||||
- WebSocket: `ws://localhost:37424` (for Roblox Studio communication)
|
||||
|
||||
### Starting Roblox Studio Communication
|
||||
|
||||
1. Open Roblox Studio with the plugin installed
|
||||
2. Press **Play** to start the server script
|
||||
3. You should see a status indicator in the top-right corner
|
||||
4. The MCP server will automatically connect
|
||||
|
||||
### Using with Claude Code
|
||||
|
||||
Once connected, you can ask Claude to:
|
||||
|
||||
```bash
|
||||
# Create a script
|
||||
"Create a Script in Workspace that prints 'Hello World'"
|
||||
|
||||
# Create a part
|
||||
"Create a red block part at position 0, 10, 0 in Workspace"
|
||||
|
||||
# Build a GUI
|
||||
"Create a ScreenGui with a TextButton that says 'Click Me'"
|
||||
|
||||
# Get hierarchy
|
||||
"Show me the hierarchy of Workspace"
|
||||
|
||||
# Execute code
|
||||
"Execute: print('Testing command')"
|
||||
```
|
||||
|
||||
## Available Tools
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `roblox_create_script` | Create a Script, LocalScript, or ModuleScript |
|
||||
| `roblox_create_part` | Create 3D parts (Block, Ball, Cylinder, etc.) |
|
||||
| `roblox_create_model` | Create model containers |
|
||||
| `roblox_create_folder` | Create folders for organization |
|
||||
| `roblox_create_gui` | Create GUI elements |
|
||||
| `roblox_set_property` | Set properties on existing objects |
|
||||
| `roblox_get_hierarchy` | Get the object hierarchy |
|
||||
| `roblox_delete_object` | Delete an object by path |
|
||||
| `roblox_execute_code` | Execute arbitrary Lua code |
|
||||
| `roblox_play` | Start playtest |
|
||||
| `roblox_stop` | Stop playtest |
|
||||
| `roblox_save_place` | Save the current place |
|
||||
|
||||
## Configuration
|
||||
|
||||
Edit `src/index.js` to change ports:
|
||||
|
||||
```javascript
|
||||
const HTTP_PORT = 37423; // Health check endpoint
|
||||
const WS_PORT = 37424; // WebSocket for Roblox Studio
|
||||
```
|
||||
|
||||
Edit `roblox-plugin/RobloxMCPServer.lua` to change plugin settings:
|
||||
|
||||
```lua
|
||||
local CONFIG = {
|
||||
PORT = 37425,
|
||||
POLL_INTERVAL = 0.1,
|
||||
DEBUG = true,
|
||||
}
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "No Roblox Studio instance connected"
|
||||
|
||||
- Make sure Roblox Studio is open
|
||||
- Make sure the server script is running (press Play)
|
||||
- Check that HTTP requests are enabled in Game Settings
|
||||
- Look for the status indicator in the top-right corner
|
||||
|
||||
### WebSocket Connection Failed
|
||||
|
||||
- Check that the MCP server is running (`npm start`)
|
||||
- Verify the WS_PORT matches between server and plugin
|
||||
- Check Windows Firewall if connection is refused
|
||||
|
||||
### Scripts Not Executing
|
||||
|
||||
- Make sure the script type is correct (Script vs LocalScript vs ModuleScript)
|
||||
- Check the Output window in Roblox Studio for errors
|
||||
- Verify the parent path is correct
|
||||
|
||||
### HTTP Requests Blocked
|
||||
|
||||
- Go to Game Settings → Security
|
||||
- Enable "Allow HTTP Requests"
|
||||
- Enable "Enable Studio Access to API Services"
|
||||
|
||||
## Development
|
||||
|
||||
### Project Structure
|
||||
|
||||
```
|
||||
roblox-mcp-server/
|
||||
├── src/
|
||||
│ └── index.js # MCP server + WebSocket server
|
||||
├── roblox-plugin/
|
||||
│ ├── RobloxMCPPlugin.lua # Toolbar plugin (optional)
|
||||
│ └── RobloxMCPServer.lua # Server script (required)
|
||||
├── package.json
|
||||
└── README.md
|
||||
```
|
||||
|
||||
### Adding New Tools
|
||||
|
||||
1. Add the tool definition to `src/index.js` in the `ListToolsRequestSchema` handler
|
||||
2. Add a case in the `CallToolRequestSchema` handler
|
||||
3. Add a corresponding handler in `roblox-plugin/RobloxMCPServer.lua`
|
||||
|
||||
## Security Notes
|
||||
|
||||
- This plugin allows executing arbitrary Lua code in Roblox Studio
|
||||
- Only use in trusted environments
|
||||
- HTTP requests must be enabled in Roblox Studio
|
||||
- Consider using a reverse proxy for production deployments
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
|
||||
## Contributing
|
||||
|
||||
Contributions welcome! Feel free to open issues or pull requests.
|
||||
Reference in New Issue
Block a user